Await Interface

await-interface.sh, contains a function that returns active interface names based off provided hint, useful for services that setup tun/tap interfaces.

The following covers how to install this branch as a submodule within your own project, and parameters that await-interface.sh currently responds to.

---

Table of Contents

• ⬆ Top of ReadMe File

• ⚡ Quick Start

  • 📝 Edit Your ReadMe File
  • 🐚 Example Bash Script
  • 💾 Commit and Push

• 📜 await-interface.sh Positional Arguments

• 🗒 Notes

• ©️ License

---

Quick Start

Bash Variables

_module_https_url='https://github.com/network-utilities/await-interface.git'
_module_relative_path='lib/modules/await-interface'

Git Commands

cd "your-project-path"

git submodule add\
 -b master\
 --name await-interface\
 "${_module_https_url}" "${_module_relative_path}"

Version Locking; recommended for those that audit every dependency...

git checkout tags/<tag_name> -b <branch_name>

... replace <tag_name> with the tag to checkout and <branch_name> with a custom name, eg...

git checkout tags/v0.0.1 -b loc-v0.0.1

Edit Your ReadMe File

Suggested additions so everyone has a good time with submodules

Clone with the following to avoid incomplete downloads


    git clone --recurse-submodules <url-for-your-project>


Update/upgrade submodules via


    git submodule update --init --recursive --remote --merge


Please review the official documentation for Git submodules...


    git help submodule


... or via [Submodules chapter][git_book__submodules] from Git.



[git_book__submodules]:
  https://git-scm.com/book/en/v2/Git-Tools-Submodules
  "Valuable information for daily use and recovering from a detached HEAD"

Example Bash Script

example-usage.sh

#!/usr/bin/env bash


## Enable sourcing via absolute path
__SOURCE__="${BASH_SOURCE[0]}"
while [[ -h "${__SOURCE__}" ]]; do
    __SOURCE__="$(find "${__SOURCE__}" -type l -ls | sed -n 's@^.* -> \(.*\)@\1@p')"
done
__DIR__="$(cd -P "$(dirname "${__SOURCE__}")" && pwd)"


source "${__DIR__}/modules/await-interface/await-interface.sh"


_interface_names_list=($(await_interface 'tun'))
printf 'Active interface name: %s\n' "${_interface_names_list[@]}"

_interface_names_string="$(await_interface 'tap0' '1' '3')"
printf 'Active interface name(s): %s\n' "${_interface_names_string}"

Testing example-usage.sh

bash example-usage.sh || echo "Exit code -> ${?}"

Utilize the above example to make similar edits to any of your project scripts that should wait for interface names.

Commit and Push

git add .gitmodules
git add lib/modules/await-interface
git add README.md


git commit -F- <<'EOF'
:heavy_plus_sign: Adds network-utilities/await-interface dependency



**Additions**


- `.gitmodules` file, tracks other Git repository code utilized by this project

- `lib/modules/await-interface` submodule, Git tracked dependency


**Edits**


- `README.md` file, documentation updates for submodules
EOF


git push origin gh-pages

🎉 Excellent 🎉 your project is now ready to begin unitizing code of this repository!

---

Await Interface API

Param	Type		Description
$1	string	required	Hint of interface name to look out for, example tun or tap0
$2	number	1	Number of seconds to sleep between checks
$3	number	10	Max number of loops before function returns error code

Returns: <string|list>, IP address or space separated list of addresses

Throws Parameter_Error: await_interface not provided an interface, when first parameter is not defined

Example: as an array

_interface_names_list=($(await_interface 'tun'))
printf 'Active interface name: %s\n' "${_interface_names_list[@]}"
#> Active interface name: tun0
#> Active interface name: tun1
#> Active interface name: tun2

Example: as a string

_interface_names_string="$(await_interface 'tap0' '1' '3')"
printf 'Active interface name(s): %s\n' "${_interface_names_string}"
#> Active interface name(s): tap0

---

Notes

Pull Requests are welcomed! Check the Community section for development tips and code of conduct.

---

License

Await Interface submodule quick start documentation
Copyright (C) 2019  S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation; version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.