diff --git a/examples/opnsense/README.md b/examples/opnsense/README.md index a2a7a1a..a76a0e6 100644 --- a/examples/opnsense/README.md +++ b/examples/opnsense/README.md @@ -1,15 +1,23 @@ -## OPNSense demo +# OPNSense Demo -Download the virtualbox snapshot from {{TODO URL}} +This example demonstrate how to manage an Opnsense server with harmony. -Start the virtualbox image +todo: add more info -This virtualbox image is configured to use a bridge on the host's physical interface, make sure the bridge is up and the virtual machine can reach internet. +## Demo instructions -Credentials are opnsense default (root/opnsense) +todo: add detailed instructions -Run the project with the correct ip address on the command line : + - setup the example execution environment + - setup your system configuration + - topology + - scores + - secrets + - build + - execute + - verify/inspect + +## Example execution + +See [learning tool documentation](./scripts/README.md) -```bash -cargo run -p example-opnsense -- 192.168.5.229 -``` diff --git a/examples/opnsense/scripts/README.md b/examples/opnsense/scripts/README.md new file mode 100644 index 0000000..efb2ca7 --- /dev/null +++ b/examples/opnsense/scripts/README.md @@ -0,0 +1,22 @@ +# Example scripts + +Scripts included in this directory have 3 purposes: + + - automate initial setup of localhost or VM (nested virtualization) for this example + - prototype a solution for an 'OpensenseLocalhostTopology' + - prototype + + +## Remarks + + - A nested VM setup should be safer + +## Automation + +### Localhost learning environment + +![localhost case](./doc/automate-opnsense-example-localhost.drawio.png) + +### Virtualized learning environment + +![localhost case](./doc/automate-opnsense-example-nested-virtualization.drawio.png) diff --git a/examples/opnsense/scripts/common b/examples/opnsense/scripts/common index 1a1f884..e0b4424 100644 --- a/examples/opnsense/scripts/common +++ b/examples/opnsense/scripts/common @@ -7,48 +7,3 @@ _fatal(){ >&2 echo stopping... exit 1 } - -is_string_empty(){ - if [ "${*:-}" != "" ]; then - return 0 - else - return 1 - fi -} - -is_debian_family()( - is_string_empty "$(apt --version 2> /dev/null )" -) - -has_ip(){ - is_string_empty "$(ip -V 2> /dev/null)" -} - -has_virsh(){ - is_string_empty "$(virsh --version 2> /dev/null)" -} - -has_virt_customize(){ - is_string_empty "$(virt-customize --version 2> /dev/null)" -} - -has_curl(){ - is_string_empty "$(curl --version 2> /dev/null)" -} -has_wget(){ - is_string_empty "$(wget --version 2> /dev/null)" -} - -install_kvm(){ - sudo apt install -y --no-install-recommends qemu-system libvirt-clients libvirt-daemon-system - sudo adduser "$USER" libvirt -} - -install_virt_customize(){ - sudo apt install -y libguestfs-tools -} - -install_wget(){ - sudo apt install -y wget -} - diff --git a/examples/opnsense/scripts/dependencies-management b/examples/opnsense/scripts/dependencies-management new file mode 100644 index 0000000..0bb0008 --- /dev/null +++ b/examples/opnsense/scripts/dependencies-management @@ -0,0 +1,45 @@ +#! /bin/bash +is_string_empty(){ + if [ "${*:-}" != "" ]; then + return 0 + else + return 1 + fi +} + +is_debian_family()( + is_string_empty "$(apt --version 2> /dev/null )" +) + +has_ip(){ + is_string_empty "$(ip -V 2> /dev/null)" +} + +has_virsh(){ + is_string_empty "$(virsh --version 2> /dev/null)" +} + +has_virt_customize(){ + is_string_empty "$(virt-customize --version 2> /dev/null)" +} + +has_curl(){ + is_string_empty "$(curl --version 2> /dev/null)" +} +has_wget(){ + is_string_empty "$(wget --version 2> /dev/null)" +} + +install_kvm(){ + sudo apt install -y --no-install-recommends qemu-system libvirt-clients libvirt-daemon-system + sudo adduser "$USER" libvirt +} + +install_virt_customize(){ + sudo apt install -y libguestfs-tools +} + +install_wget(){ + sudo apt install -y wget +} + diff --git a/examples/opnsense/scripts/doc/automate-opnsense-example-localhost.drawio.png b/examples/opnsense/scripts/doc/automate-opnsense-example-localhost.drawio.png new file mode 100644 index 0000000..a038304 Binary files /dev/null and b/examples/opnsense/scripts/doc/automate-opnsense-example-localhost.drawio.png differ diff --git a/examples/opnsense/scripts/doc/automate-opnsense-example-nested-virtualization.drawio.png b/examples/opnsense/scripts/doc/automate-opnsense-example-nested-virtualization.drawio.png new file mode 100644 index 0000000..9823d6c Binary files /dev/null and b/examples/opnsense/scripts/doc/automate-opnsense-example-nested-virtualization.drawio.png differ diff --git a/examples/opnsense/scripts/doc/automate-opnsense-example.drawio b/examples/opnsense/scripts/doc/automate-opnsense-example.drawio new file mode 100644 index 0000000..8f9be89 --- /dev/null +++ b/examples/opnsense/scripts/doc/automate-opnsense-example.drawio @@ -0,0 +1,321 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/opnsense/scripts/harmony-ve b/examples/opnsense/scripts/harmony-ve new file mode 100755 index 0000000..60ffc95 --- /dev/null +++ b/examples/opnsense/scripts/harmony-ve @@ -0,0 +1,105 @@ + +#! /bin/bash + +harmony-ve()( + + set -eu + + [ "${1:-}" != "-d" ] || { set -x ; shift ; } + trap '[ "$?" = "0" ] || >&2 echo ABNORMAL TERMINATION' EXIT + + SCRIPTS_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")") + . "${SCRIPTS_DIR}/common" + + _short_help(){ + + cat <<-EOM + + NAME + + harmony-ve + + DESCRIPTION + + CLI management toolkit for Harmony Virtualized Execution Environment + + SYNOPSYS + + harmony-ve [GLOBAL_OPTIONS] COMMAND [OPTIONS] + + harmony-ve dependencies # manage localhost depend + harmony-ve network # manage localhost netork + + harmony-ve opnsense-img-src # manage opnsense OS source images + harmony-ve opnsense-img # manage opnsense OS images + + harmony-ve vm # manage vm + +EOM + + } + + _extra_help(){ + + cat <<-EOM + + DESCRIPTION + + Automation CLI to easily provision and manage a Virtualized Execution Environment for testing and learning Harmony. + + This tool allows: + - new harmony users to start testing within 15 minutes on their development desktop + - automate virtualized test in pipeline + + GLOBAL_OPTIONS + + -d Debug mode. + + WARNINGS + + This script is experimetal. Use with caution. +EOM + + + } + + + # Implement functions + +case "${1:-}" in + + "") + _short_help + ;; + -h|--help) + _short_help + _extra_help + ;; + # Commands entrypoints + deps|dependencies) + harmony-ve-dependencies "${@:2}" + ;; + net|network) + harmony-ve-network"${@:2}" + ;; + img-src|opnsense-img-src) + harmony-ve-opnsense-img-src "${@:2}" + ;; + img|opnsense-img) + harmony-ve-opnsense-img "${@:2}" + ;; + vm) + harmony-ve-vm "${@:2}" + ;; + + *) + _warn "Unknown COMMAND '$1'" + exit 1 + ;; +esac + +) + + +[ "$0" != "${BASH_SOURCE}" ] || harmony-ve "${@}" + diff --git a/examples/opnsense/scripts/devops b/examples/opnsense/scripts/harmony-ve-dependencies similarity index 64% rename from examples/opnsense/scripts/devops rename to examples/opnsense/scripts/harmony-ve-dependencies index d35a220..a5abf83 100755 --- a/examples/opnsense/scripts/devops +++ b/examples/opnsense/scripts/harmony-ve-dependencies @@ -1,32 +1,32 @@ #! /bin/bash -devops()( +harmony-ve-dependencies()( set -eu [ "${1:-}" != "-d" ] || { set -x ; shift ; } trap '[ "$?" = "0" ] || >&2 echo ABNORMAL TERMINATION' EXIT - BASE_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")/..") - + SCRIPTS_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")") + . "${SCRIPTS_DIR}/common" _short_help(){ cat <<-EOM NAME - devops -- utility script for this example ($(basename ${BASE_DIR})) + + harmony-ve-dependencies + + DESCRIPTION + + Manage localhost dependencies needed for Harmony Virtual Execution Environment SYNOPSYS - devops [GLOBAL_OPTIONS] COMMAND [OPTIONS] + devops-dependencies [GLOBAL_OPTIONS] COMMAND [OPTIONS] - devops up [-f] # Ensure that everything needed by the example is ready - devops down # Destroy everything - - devops check-dependencies # Check that dependencies are installed - devops install-dependencies # Check that dependencies are installed - devops setup-network # Prepare the network - devops + devops check # Check that dependencies are installed + devops install # Install missing dependencies EOM @@ -49,7 +49,7 @@ EOM _check_dependencies(){ - . "${BASE_DIR}/scripts/common" + . "${SCRIPTS_DIR}/dependencies-management" missing=0 NEED_IP=false NEED_KVM=false @@ -73,8 +73,7 @@ EOM } has_wget || has_curl || { missing=$(( missing + 1)); - _warn "wget and curl commands are missing"; - NEED_WGET=true + _warn "wget and curl commands are missing"; NEED_WGET=true } @@ -90,23 +89,26 @@ EOM case "${1:-}" in - -h|--help|"") + "") + _short_help + ;; + -h|--help) _short_help _extra_help ;; - check-dependencies) + cdeps|check-dependencies) _check_dependencies if [ "$missing" -gt 0 ]; then exit 1 fi _warn No missing dependencies ;; - install-dependencies) + ideps|install-dependencies) _check_dependencies _install_dependencies ;; *) - echo "Unknown COMMAND '$1'" + _warn "Unknown COMMAND '$1'" exit 1 ;; esac @@ -114,5 +116,5 @@ esac ) -[ "$0" != "${BASH_SOURCE}" ] || devops "${@}" +[ "$0" != "${BASH_SOURCE}" ] || harmony-ve-dependencies "${@}" diff --git a/examples/opnsense/scripts/harmony-ve-network b/examples/opnsense/scripts/harmony-ve-network new file mode 100755 index 0000000..fb0e62f --- /dev/null +++ b/examples/opnsense/scripts/harmony-ve-network @@ -0,0 +1,74 @@ + +#! /bin/bash + +harmony-ve-network()( + + set -eu + + [ "${1:-}" != "-d" ] || { set -x ; shift ; } + trap '[ "$?" = "0" ] || >&2 echo ABNORMAL TERMINATION' EXIT + + BASE_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")/..") + + _short_help(){ + + cat <<-EOM + + NAME + + harmony-ve-network + + DESCRIPTION + + Modify localhost network for Harmony Virtual Execution Environment + SYNOPSYS + + harmony-ve-network [GLOBAL_OPTIONS] COMMAND [OPTIONS] + + harmony-ve-network check + harmony-ve-network setup + harmony-ve-network cleanup + +EOM + + } + + _extra_help(){ + + cat <<-EOM + + GLOBAL_OPTIONS + + -d Debug mode. + + WARNINGS + + This script is experimetal. Use with caution. +EOM + + } + + + # Implement functions + +case "${1:-}" in + + "") + _short_help + ;; + -h|--help) + _short_help + _extra_help + ;; + # Commands entrypoints + *) + _warn "Unknown COMMAND '$1'" + exit 1 + ;; +esac + +) + + +[ "$0" != "${BASH_SOURCE}" ] || harmony-ve-network "${@}" + diff --git a/examples/opnsense/scripts/harmony-ve-opnsense-img b/examples/opnsense/scripts/harmony-ve-opnsense-img new file mode 100755 index 0000000..e3ad33d --- /dev/null +++ b/examples/opnsense/scripts/harmony-ve-opnsense-img @@ -0,0 +1,81 @@ + +#! /bin/bash + +harmony-ve-opnsense-img()( + + set -eu + + [ "${1:-}" != "-d" ] || { set -x ; shift ; } + trap '[ "$?" = "0" ] || >&2 echo ABNORMAL TERMINATION' EXIT + + SCRIPTS_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")") + . "${SCRIPTS_DIR}/common" + + DEFAULT_KVM_IMG_DIR=/var/lib/libvirt/images + KVM_IMG_DIR=${KVM_IMG_DIR:-$DEFAULT_KVM_IMG_DIR} + [ -d "$KVM_IMG_DIR" ] || mkdir -p "${KVM_IMG_DIR}" + + + _short_help(){ + + cat <<-EOM + + NAME + + harmony-ve-opnsense-img + + DESCRIPTION + + Manage opnsense images needed by Harmony Virtual Execution Environment + SYNOPSYS + + harmony-vee-opnsense-img [GLOBAL_OPTIONS] COMMAND [OPTIONS] + + harmony-vee-opnsense-img list [--remote] + harmony-vee-opnsense-img new NAME + harmony-vee-opnsense-img update NAME + harmony-vee-opnsense-img delete [NAME] + +EOM + + } + + _extra_help(){ + + cat <<-EOM + + GLOBAL_OPTIONS + + -d Debug mode. + + WARNINGS + + This script is experimetal. Use with caution. +EOM + + } + + + # Implement functions + +case "${1:-}" in + + "") + _short_help + ;; + -h|--help) + _short_help + _extra_help + ;; + # Commands entrypoints + *) + _warn "Unknown COMMAND '$1'" + exit 1 + ;; +esac + +) + + +[ "$0" != "${BASH_SOURCE}" ] || harmony-ve-opnsense-img "${@}" + diff --git a/examples/opnsense/scripts/harmony-ve-opnsense-img-src b/examples/opnsense/scripts/harmony-ve-opnsense-img-src new file mode 100755 index 0000000..dd8fb68 --- /dev/null +++ b/examples/opnsense/scripts/harmony-ve-opnsense-img-src @@ -0,0 +1,91 @@ + +#! /bin/bash + +harmony-ve-opnsense-img-src()( + + set -eu + + [ "${1:-}" != "-d" ] || { set -x ; shift ; } + trap '[ "$?" = "0" ] || >&2 echo ABNORMAL TERMINATION' EXIT + + SCRIPTS_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")") + . "${SCRIPTS_DIR}/common" + + OPNSENSE_SRC_BASE_URL=https://pkg.opnsense.org/releases/ + DEFAULT_KVM_IMG_DIR=/var/lib/libvirt/images + KVM_IMG_DIR=${KVM_IMG_DIR:-$DEFAULT_KVM_IMG_DIR} + [ -d "$KVM_IMG_DIR" ] || mkdir -p "${KVM_IMG_DIR}" + + + _short_help(){ + + cat <<-EOM + + NAME + + harmony-ve-opnsense-img-src + + DESCRIPTION + + Manage opnsense source images needed by Harmony Virtual Execution Environment + + SYNOPSYS + + harmony-vee-opnsense-img-src [GLOBAL_OPTIONS] COMMAND [OPTIONS] + + harmony-vee-opnsense-img-src list [--remote] + harmony-vee-opnsense-img-src check [VERSION] + harmony-vee-opnsense-img-src download [VERSION] + harmony-vee-opnsense-img-src delete [VERSION] + +EOM + + } + + _extra_help(){ + + cat <<-EOM + + GLOBAL_OPTIONS + + -d Debug mode. + + WARNINGS + + This script is experimetal. Use with caution. + + DETAILS + + - for 'list', show local images available + - for 'list --remote', show available upstream images + - for 'check' and 'download', when no VERSION is specified, use the latest + - for 'delete', when no VERSION is specified, delete all image + - use the 'nano' flavor +EOM + + } + + + # Implement functions + +case "${1:-}" in + + "") + _short_help + ;; + -h|--help) + _short_help + _extra_help + ;; + # Commands entrypoints + *) + _warn "Unknown COMMAND '$1'" + exit 1 + ;; +esac + +) + + +[ "$0" != "${BASH_SOURCE}" ] || harmony-ve-opnsense-img-src "${@}" + diff --git a/examples/opnsense/scripts/harmony-ve-vm b/examples/opnsense/scripts/harmony-ve-vm new file mode 100755 index 0000000..d39c4b0 --- /dev/null +++ b/examples/opnsense/scripts/harmony-ve-vm @@ -0,0 +1,77 @@ + +#! /bin/bash + +harmony-ve-vm()( + + set -eu + + [ "${1:-}" != "-d" ] || { set -x ; shift ; } + trap '[ "$?" = "0" ] || >&2 echo ABNORMAL TERMINATION' EXIT + + BASE_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")/..") + + _short_help(){ + + cat <<-EOM + + NAME + + harmony-ve-mv + + DESCRIPTION + + Manage virtalized hosts (VM) dependencies by Harmony Virtual Execution Environment + + SYNOPSYS + + harmony-ve-vm [GLOBAL_OPTIONS] COMMAND [OPTIONS] + + harmony-ve-vm list + harmony-ve-vm create + harmony-ve-vm start + harmony-ve-vm stop + harmony-ve-vm login + +EOM + + } + + _extra_help(){ + + cat <<-EOM + + GLOBAL_OPTIONS + + -d Debug mode. + + WARNINGS + + This script is experimetal. Use with caution. +EOM + + } + + + # Implement functions + +case "${1:-}" in + + "") + _short_help + ;; + -h|--help) + _short_help + _extra_help + ;; + # Commands entrypoints + *) + _warn "Unknown COMMAND '$1'" + exit 1 + ;; +esac + +) + + +[ "$0" != "${BASH_SOURCE}" ] || harmony-ve-vm "${@}" + diff --git a/examples/opnsense/scripts/learn-harmony b/examples/opnsense/scripts/learn-harmony new file mode 100755 index 0000000..3bab681 --- /dev/null +++ b/examples/opnsense/scripts/learn-harmony @@ -0,0 +1,75 @@ +#! /bin/bash + +learn-harmony()( + + set -eu + + [ "${1:-}" != "-d" ] || { set -x ; shift ; } + trap '[ "$?" = "0" ] || >&2 echo ABNORMAL TERMINATION' EXIT + + BASE_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")/..") + SCRIPTS_DIR=$(readlink -f "$(dirname "${BASH_SOURCE}")") + . "${SCRIPTS_DIR}/common" + export PATH=$SCRIPTS_DIR:$PATH + + _short_help(){ + + cat <<-EOM + + NAME + learn-harmony -- Harmony Learning Tool prototype + ($(basename ${BASE_DIR}) example) + + SYNOPSYS + + learn-harmony [GLOBAL_OPTIONS] COMMAND [OPTIONS] + + learn-harmony list # List learning steps + learn-harmony show STEP # Show instruction of step STEP + learn-harmony check [STEP] # Verify that your ready to begin step STEP+1 + +EOM + + } + + _extra_help(){ + + cat <<-EOM + + GLOBAL_OPTIONS + + -d Debug mode. + + WARNINGS + + This script is experimetal. Use with caution. +EOM + + } + +case "${1:-}" in + + -h|--help|"") + _short_help + _extra_help + ;; + ls|list) + echo "not implemented" + ;; + show) + echo "not implemented" + ;; + verify) + echo "not implemented" + ;; + *) + _warn "Unknown COMMAND '$1'" + exit 1 + ;; +esac + +) + + +[ "$0" != "${BASH_SOURCE}" ] || learn-harmony "${@}" +