cli

#!/bin/bash
set -e -u

# Set default values for unset variables
: ${GANTRY_DEBUG=0}
: ${GANTRY_INSIDE_DOCKER=0}
: ${DIGITALOCEAN_TOKEN=}

# Echo commands in debug mode
[ ${GANTRY_DEBUG} -eq 1 ] && set -x
export SHELLOPTS

# Without this the Ansible Network CLI module will fail to connect to the router due to unknown SSH host key
export ANSIBLE_PARAMIKO_HOST_KEY_AUTO_ADD=True
export ANSIBLE_HOST_KEY_AUTO_ADD=True
export ANSIBLE_HOST_KEY_CHECKING=False # for junos_config use of ncclient.connect()

# Disable automated fact gathering as the host on which Ansible runs is not interesting to us, we're interested
# in what happens inside Docker containers on the host, and having to say gather_facts: false for every - hosts:
# section in the Ansible templates is really annoying, as is waiting for fact gathering that isn't needed.
export ANSIBLE_GATHERING=explicit

# I haven't found a use for, or way to make, retry files work yet, and when playbooks are taken from a Docker
# bind mount that is read-only to the container Ansible warns about being unable to write the retry file. Just
# disable it ...
export ANSIBLE_RETRY_FILES_ENABLED=no

# Enable Ansible task profiling (causes Ansible to show how long tasks take)
export ANSIBLE_CALLBACK_WHITELIST=profile_tasks

SELF="$0"
BASEDIR=$(dirname $0)
PLAYBOOKS_DIR="${BASEDIR}/playbooks"
PLAYBOOK_VARS="${BASEDIR}/playbook-vars.yml"
DIGITAL_OCEAN_REGION="ams3"
DIGITAL_OCEAN_BASE_OS_SLUG="ubuntu-18-04-x64"
NOT_DEPLOYED="-"
INVENTORY_PLUGIN_CONFIG_FILE="${BASEDIR}/docker_machine.yml"
CHILD_PIDS=( )

export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=1800
export ANSIBLE_PERSISTENT_CONNECT_TIMEOUT=1800 # for: https://github.com/ansible/ansible/commit/f547c88adec71b8822cfd30df1a5850bdc778c02

wait_for_children() {
    # wait for subprocesses to finish
    for PID in ${CHILD_PIDS[*]}; do
        wait $PID
    done
    CHILD_PIDS=( )
}

get_longest_length() {
    LEN=-1
    for EL in $*; do [ ${#EL} -gt $LEN ] && LEN=${#EL}; done
    echo $LEN
}

my_timestamp() {
    date +'%Y-%m-%d %H:%M:%S %z'
}

my_log() {
    echo $(my_timestamp): $*
}

abort() {
    echo >&2 $(my_timestamp): ERROR: $*
    exit 1
}

abort_with_usage() {
    show_usage
    exit 2
}

check_dependencies() {
    for DEP in $*; do
        which $DEP >/dev/null || abort "ERROR: Please install ${DEP}. Aborting."
    done
}

check_is_docker_distribution() {
    [ "${GANTRY_INSIDE_DOCKER}" -eq 1 ]
}

check_digitalocean_api_token() {
    [ -z "${DIGITALOCEAN_TOKEN}" ] && abort "You must supply environment variable DIGITALOCEAN_TOKEN."
    return 0
}

check_proceed() {
    read -p "$(my_timestamp): Do you wish to proceed? [y/N] " CHOICE
    test 'y' == "${CHOICE}"
}

prefix_console_output() {
    LOG_PREFIX="$1"
    # save and redirect STDOUT and STDERR file descriptors to setup output prefixing 
    exec 5>&1 6>&2 1> >(sed "s/^/${LOG_PREFIX}/") 2> >(sed "s/^/${LOG_PREFIX}/")
}

unprefix_console_output() {
    # restore original STDOUT and STDERR file descriptors
    exec 1>&5 2>&6
}

create-machine() {
    MACHINE_NAME="$1"
    MACHINE_SIZE="$2"
    REGION="$3"
    TAGS="$4"

    # Based on the rules for tag names stated here: https://developers.digitalocean.com/documentation/v2/#tags
    # Commas are not in the allowed set but are used by Docker Machine to separate tags from one another.
    TAGS="$(echo $TAGS | tr '.' '-' | tr -c -d 'a-zA-Z0-9:_,-')"

    my_log "Checking if a Docker Machine with name ${MACHINE_NAME} already exists.."
    if docker-machine ip ${MACHINE_NAME} &>/dev/null; then
        my_log "Docker Machine ${MACHINE_NAME} found."
    else
        my_log "Creating new DigitalOcean Droplet ${MACHINE_NAME} with Docker Machine (region: ${REGION}, image: ${DIGITAL_OCEAN_BASE_OS_SLUG}, size: ${MACHINE_SIZE}).."
        docker-machine create \
        --driver digitalocean \
        --digitalocean-access-token ${DIGITALOCEAN_TOKEN} \
        --digitalocean-region ${REGION} \
        --digitalocean-image ${DIGITAL_OCEAN_BASE_OS_SLUG} \
        --digitalocean-size ${MACHINE_SIZE} \
        --digitalocean-tags ${TAGS} \
        ${MACHINE_NAME}
        my_log "Docker Machine creation complete."
    fi
    }

destroy_machine() {
    MACHINE_NAME="$1"
    docker-machine rm --force ${MACHINE_NAME}
}

run_playbook() {
    PLAYBOOK_PATH="$1"
    ONLY_THIS_HOST="$2"
    shift 2

    # support multiple playbook files by replacing commas with spaces
    PLAYBOOK_PATH=${PLAYBOOK_PATH//,/ }

    EXTRA_ARGS=
    [ "${ONLY_THIS_HOST}" == "all" ] || EXTRA_ARGS="--limit=${ONLY_THIS_HOST}"

    my_log "Executing Ansible playbook ${PLAYBOOK_PATH}.."
    ansible-playbook $* -i ${INVENTORY_PLUGIN_CONFIG_FILE} ${EXTRA_ARGS} -e "@playbook-vars.yml" ${PLAYBOOK_PATH}
}

export_component_vars() {
    COMPONENT="$1"
    if [ "${COMPONENT}" == "routinator" ]; then
        export COMPONENT_NAME="routinator"
        export COMPONENT_VERSION="latest"
        export DOCKER_SERVICE="${COMPONENT_NAME}"
        export DOCKER_TAG="${COMPONENT_VERSION}"
        export DOCKER_MACHINE_NAME="${COMPONENT_NAME}"
    else
        export COMPONENT_NAME="${COMPONENT%:*}"
        export COMPONENT_VERSION="${COMPONENT##*:}"
        export DOCKER_SERVICE="router"
        export DOCKER_TAG="${COMPONENT_VERSION}"
        export DOCKER_MACHINE_NAME="${COMPONENT_NAME}-${COMPONENT_VERSION}"
    fi
}

get_machine_property() {
    MACHINE_NAME="$1"
    PROPERTY="$2"
    docker-machine ${PROPERTY} ${MACHINE_NAME} 2>/dev/null || echo "${NOT_DEPLOYED}"
}

# outputs lines in the form: <COMPONENT>|<STATUS>|<IP ADDRESS>|<VM SIZE>
# usage:
#   get_deployment_report [--component <REGEX> [--not] [--no-status]]
#   get_deployment_report [--status <REGEX> [--not]]
get_deployment_report() {
    COMPONENT_REGEX=".+"
    STATUS_REGEX=".+"
    COMPONENT_NOT=
    STATUS_NOT=
    NO_STATUS=0
    if [[ $# -ge 3 && "$3" == "--not" ]]; then
        NOT=v
        # [ "$1" == "--component" ] && STATUS_REGEX="^$"
        # [ "$1" == "--status" ] && COMPONENT_REGEX="^$"
    fi
    [[ $# -ge 2 && "$1" == "--component" ]] && COMPONENT_NOT="$NOT" && COMPONENT_REGEX="$2"
    [[ $# -ge 2 && "$1" == "--status" ]] && STATUS_NOT="$NOT" && STATUS_REGEX="$2"

    NUM_ARGS_MINUS_ONE=$(($# - 1))
    [ "${NUM_ARGS_MINUS_ONE}" -gt 0 ] && shift ${NUM_ARGS_MINUS_ONE}
    [[ $# -ge 1 && $1 == "--no-status" ]] && NO_STATUS=1

    for PLAYBOOK_PATH in $(ls ${PLAYBOOKS_DIR}/playbook-*.yml | grep -E${COMPONENT_NOT} ${COMPONENT_REGEX}); do
        COMPONENT=$(basename ${PLAYBOOK_PATH} | sed -e 's/^playbook-//' -e 's/\.yml//')
        if [ "${NO_STATUS}" == "1" ]; then
            echo "${COMPONENT}|||"
        else
            export_component_vars "${COMPONENT}"
            STATUS="$(get_machine_property ${DOCKER_MACHINE_NAME} status | grep -E${STATUS_NOT} ${STATUS_REGEX})"
            if [ ! -z "${STATUS}" ]; then
                IP="$(get_machine_property ${DOCKER_MACHINE_NAME} ip)"
                VM_SIZE=$(get_playbook_specific_var "${PLAYBOOK_PATH}" DROPLET_SIZE)
                echo "${COMPONENT}|${STATUS}|${IP}|${VM_SIZE}"
            fi
        fi
    done
}

get_playbook_global_var() {
    VAR_TO_GET="$1"
    grep -E "^${VAR_TO_GET}: .+" ${PLAYBOOK_VARS} | cut -d ':' -f 2 | tr -d '[:space:]'
}

get_playbook_specific_var() {
    PLAYBOOK="$1"
    VAR_TO_GET="$2"
    grep -E "^# ${VAR_TO_GET}=" ${PLAYBOOK} | cut -d '=' -f 2
}

print_status() {
    INDENT=""
    FORMAT="%s%-20s %-10s %-16s %s\n"
    printf "${FORMAT}" "${INDENT}" "NAME" "STATE" "IP ADDRESS" "VM SIZE"
    OLDIFS=$IFS; IFS=$'\n'
    for REPORT_LINE in $(get_deployment_report); do
        COMPONENT="$(echo ${REPORT_LINE} | cut -d '|' -f 1)"
        STATUS="$(echo ${REPORT_LINE} | cut -d '|' -f 2)"
        IP="$(echo ${REPORT_LINE} | cut -d '|' -f 3)"
        VM_SIZE="$(echo ${REPORT_LINE} | cut -d '|' -f 4)"
        printf "${FORMAT}" "${INDENT}" "${COMPONENT}" "${STATUS}" "${IP}" "${VM_SIZE}"
    done
    IFS=${OLDIFS}
}

get_undeployed_component_names() {
    OLDIFS=$IFS; IFS=$'\n'
    for REPORT_LINE in $(get_deployment_report); do
        COMPONENT="$(echo ${REPORT_LINE} | cut -d '|' -f 1)"
        STATUS="$(echo ${REPORT_LINE} | cut -d '|' -f 2)"
        [ "${STATUS}" == "${NOT_DEPLOYED}" ] && echo ${COMPONENT}
    done
    IFS=${OLDIFS}
}

get_deployed_component_names() {
    docker-machine ls -q
}

undeploy_many() {
    FORCE=$1; shift
    NAMES_ARE_MACHINE_NAMES=$1; shift
    UNDEPLOY_COMPONENTS=$*
        NUM_COMPONENTS_TO_UNDEPLOY=$(echo ${UNDEPLOY_COMPONENTS} | wc -w)

    [ $NUM_COMPONENTS_TO_UNDEPLOY -le 0 ] && return

    if [ "${FORCE}" -eq 0 ]; then
        my_log "You are about to undeploy ${NUM_COMPONENTS_TO_UNDEPLOY} components: " ${UNDEPLOY_COMPONENTS}
        check_proceed || return
    fi

    MAX_NAME_LEN=$(get_longest_length ${UNDEPLOY_COMPONENTS})

    for COMPONENT in ${UNDEPLOY_COMPONENTS}; do
        prefix_console_output "$(printf "[%-${MAX_NAME_LEN}s] " ${COMPONENT})"

        # undeploy one component in the background with log prefixing enabled
        (
            [ ${GANTRY_DEBUG} -eq 1 ] && set -x
            if [ $NAMES_ARE_MACHINE_NAMES -eq 0 ]; then
                export_component_vars "${COMPONENT}"
                my_log "Destroying ${COMPONENT} host Docker Machine ${DOCKER_MACHINE_NAME}.."
                destroy_machine ${DOCKER_MACHINE_NAME}
            else
                my_log "Destroying Docker Machine ${COMPONENT}"
                destroy_machine ${COMPONENT}
            fi
        ) &

        # capture the PID of the launched subprocess
        CHILD_PIDS+=( $! )

        unprefix_console_output
    done

    wait_for_children
}

deploy_many() {
    REGION="${DIGITAL_OCEAN_REGION}"
    [[ $# -ge 1 && "$1" == "--region" ]] && REGION=$2 && shift 2

    declare -a DEPLOY_COMPONENTS
    declare -a OTHER_ARGS
    for ARG in $*; do
        PLAYBOOK_PATH="${PLAYBOOKS_DIR}/playbook-${ARG}.yml"
        if [ -f "$PLAYBOOK_PATH" ]; then
            DEPLOY_COMPONENTS+=( ${ARG} )
        else
            OTHER_ARGS+=( ${ARG} )
        fi
    done

    my_log "Components to deploy: ${DEPLOY_COMPONENTS[@]}"
    my_log "Arguments to pass to Ansible: ${OTHER_ARGS[@]}"

    check_digitalocean_api_token

    for COMPONENT in ${DEPLOY_COMPONENTS[@]}; do
        PLAYBOOK_PATH="${PLAYBOOKS_DIR}/playbook-${COMPONENT}.yml"
        [ ! -e "${PLAYBOOK_PATH}" ] && abort "No Ansible playbook found for ${COMPONENT}."
    done

    announce-takeoff

    MAX_NAME_LEN=$(get_longest_length ${DEPLOY_COMPONENTS[@]})

    for COMPONENT in ${DEPLOY_COMPONENTS[@]}; do
        prefix_console_output "$(printf "[%-${MAX_NAME_LEN}s] " ${COMPONENT})"

        # deploy one component in the background with log prefixing enabled
        # Note this assumes that the Docker Machine CA files ca.pem and ca-key.pem already exist in ~/.docker/machines/certs/.
        # Otherwise parallel invocations of docker-machine create may all attempt to create the CA thereby overwriting the files
        # needed to authenticate with machines that used client certs generated using earlier created CA files.
        # See: 
        #   - https://github.com/docker/machine/issues/3634
        #   - https://frank.sauerburger.io/2018/08/01/create-docker-machine-with-custom-certificates.html
        (
            [ ${GANTRY_DEBUG} -eq 1 ] && set -x
            PLAYBOOK_PATH="${PLAYBOOKS_DIR}/playbook-${COMPONENT}.yml"
            export_component_vars "${COMPONENT}"
            VM_SIZE=$(get_playbook_specific_var "${PLAYBOOK_PATH}" DROPLET_SIZE)
            [ -z "${VM_SIZE}" ] && abort "Internal error: No Droplet size specified for ${COMPONENT}."
            DO_TAGS="gantry_component:${COMPONENT_NAME},gantry_component_version:${COMPONENT_VERSION}"
            if [ "${COMPONENT}" == "routinator" ]; then
                DO_TAGS="${DO_TAGS},gantry_type:rpkicache"
            else
                DO_TAGS="${DO_TAGS},gantry_type:router"
            fi

            my_log "Deploying Docker Machine ${DOCKER_MACHINE_NAME} for component ${COMPONENT} using Droplet size ${VM_SIZE} in region ${REGION} with tags '${DO_TAGS}'.."
            create-machine ${DOCKER_MACHINE_NAME} ${VM_SIZE} ${REGION} ${DO_TAGS}
        ) &

        # capture the PID of the launched subprocess
        CHILD_PIDS+=( $! )

        unprefix_console_output
    done

    wait_for_children

    for COMPONENT in ${DEPLOY_COMPONENTS[@]}; do
        prefix_console_output "$(printf "[%-${MAX_NAME_LEN}s] " ${COMPONENT})"

        # deploy one component in the background with log prefixing enabled
        (
            [ ${GANTRY_DEBUG} -eq 1 ] && set -x
            PLAYBOOK_PATH="${PLAYBOOKS_DIR}/playbook-${COMPONENT}.yml"
            export_component_vars "${COMPONENT}"
            my_log "Deploying ${COMPONENT} on Docker Machine ${DOCKER_MACHINE_NAME} using Ansible playbook ${PLAYBOOK_PATH}.."
            run_playbook ${PLAYBOOK_PATH} ${DOCKER_MACHINE_NAME} ${OTHER_ARGS[@]}
        ) &

        # capture the PID of the launched subprocess
        CHILD_PIDS+=( $! )

        unprefix_console_output
    done

    wait_for_children
}

announce-takeoff() {
    cat >&2 <<'EOF'

                           ``-.-:::::/---``                           
                     ``-:/++++////////+oosyyo+:.`                     
                  .-///:-.``             ``.:+shhy/.                  
               `-:::.`                         `-+sdy+.               
             .::-.`               ``              `./ydy-             
           .---`                `-//-`               `:ymy-           
         `--.`                 `:////:`                `:ymy.         
        .--`                  .:////+++.                 `+md:        
       .-.`                 `-://////+o+-`                 -hms       
      -..                 ``-:///////+sso:``                .hNs`     
     ...               ````-::///////+syso:````              .hNo     
    .-.`             `````-:::///////+shhy+-`````             -mN:    
    -.`             `````-::::///////+shdhs/-`````             oNd`   
   .-.             `````.:::::///////+shmmho/-`````            `mN/   
   -.`             `````-::::///+osyyhhdmmms+/.````             yNs   
   `.`            `````--:::/ossssyyyyydmNmho/:`````            oNd   
   ..`            ````.-:::+yssosyyhhhhhhmNds//-````            +Nd   
   `.`            ````--:::yyo+/+osyhmNmddNmy+//.```            oNd   
   -.`             ``.--:::yy+///+oshNMNddNmho//:``             yNs   
   .-.             ``.--:::+hsooooosyhdhhmNNdo///.`            `mN/   
    -.`             `.--::::+ssssssssyyhdmNNds///-`            oNd`   
    .-.`           `..--::::://+ossyyhhyydNNmy+///`           -mN:    
     ...           `.--:::::://///++++//ohNNmy+///.          .hNo     
      -..          :syy+:::shhh+///hhhy/ohNMMNy///.         .hNs`     
       .-.`        /yhd+:::dMMMo///MMMm/+ymMMMm+++:        -hms       
        .--`       .-:/yhhhysyyhhhhhhhhhdmNNNmhmNNd`     `+md:        
         `--.`     ..--dmNN+:/+NMMM///+MMMMNNdyMMNm`   `:ymy.         
           .---`  `osyy++oshhhhhyhhhhhhhhdmMMNmso+/  `:ymy-           
             .::-.`oyhd:::/NMMM+///MMMN++sdMMMN+///./ydy-             
               `-:::::/yhhhyyyyhhhhhhyhhdmNNNNdmmmddy+.               
                  .-///oyhm+://NMMM///+MMMNmmdhdhy/.                  
                     ``-:/+++++yhhdoooshhhyyo+:.`                     
                           ``-.-:::::::--``                           

EOF
}

show_usage() {
    BASENAME="$(basename $0)"
    check_is_docker_distribution && BASENAME=gantry
    cat >&2 <<EOF
Gantry: "a structure built on a rocket launch pad to facilitate assembly and servicing"

NLnet Labs Gantry is a tool for deploying and testing network routers in the cloud, built to support the NLnet Labs Routinator project.

Usage: ${BASENAME} help|--help

Component management commands:
       ${BASENAME} deploy   <COMPONENT> [<COMPONENT>..] [--region <REGION:default=${DIGITAL_OCEAN_REGION}>] 
       ${BASENAME} docker   <COMPONENT> ..commands..
       ${BASENAME} exec     <COMPONENT> ..commands..
       ${BASENAME} ip       <COMPONENT>
       ${BASENAME} logs     <COMPONENT> [--follow]
       ${BASENAME} ssh      <COMPONENT> [--host]
       ${BASENAME} status
       ${BASENAME} undeploy <COMPONENT> [<COMPONENT>..] [--force]

Docker registry commands:
       ${BASENAME} registry ls|deploy|publish
       ${BASENAME} registry rm <repo>/<image>:<tag>

Test suite commands:
       ${BASENAME} test     <COMPONENT>|all [<SINGLE_PLAYBOOK_YML_FILE_IN_DATA_DIR>]
EOF

    check_is_docker_distribution && cat >&2 <<EOF

Wrapper commands:
       ${BASENAME} shell
       ${BASENAME} upgrade

Wrapper options:
       ${BASENAME} --data-dir <PATH/TO/YOUR/DATA/FILES:default=${GANTRY_BIND_MOUNT_HOST_DIR}>
       ${BASENAME} --version
EOF

    cat >&2 <<EOF

Where COMPONENT can be one of: (deploy and undeploy also accept special component 'all')
EOF

    INDENT="       "
    FORMAT="%s%-20s %s\n"
    printf "${FORMAT}" "${INDENT}" "COMPONENT" "VENDOR"
    for REPORT_LINE in $(get_deployment_report --no-status); do
        COMPONENT="$(echo ${REPORT_LINE} | cut -d '|' -f 1)"
        VENDOR=$(get_playbook_specific_var "${PLAYBOOKS_DIR}/playbook-${COMPONENT}.yml" VENDOR)
        if [ ! -z "${VENDOR}" ]; then
            printf "${FORMAT}" "${INDENT}" "${COMPONENT}" "${VENDOR}"
        fi
    done
}

cleanup() {
    if [[ "${GANTRY_INSIDE_DOCKER}" -eq "1" && "$$" -eq 1 ]]; then
        # We are running inside a Docker container and we are process ID 1. This means that we are the
        # Docker 'run' invocation of this container. If there are any ExecIDs for this container these
        # identify other invocations of commands via Docker 'exec' inside this same container. If we
        # exit now we will kill those commands, even if they are still running. Instead wait until they
        # have completed before exiting.
        OUTPUT_DOT=0
        while docker inspect gantry -f "{{ .ExecIDs }}" | fgrep -qv '[]'; do
            if [ ${OUTPUT_DOT} -eq 0 ]; then
                OUTPUT_DOT=1
                echo -n >&2 "Waiting for all Gantry processes to finish: "
            else
                echo -n .
            fi
            sleep 5s
        done
    fi
}

ctrl_c() {
    my_log "Aborting.."
    for PID in ${CHILD_PIDS[*]}; do
        kill -TERM $PID
    done
}

trap ctrl_c INT
trap cleanup EXIT

check_dependencies \
    docker-machine \
    ansible-playbook

[ $# -lt 1 ] && abort_with_usage

MODE="$1"; shift
case "$MODE" in
    shell)
        [ "${GANTRY_INSIDE_DOCKER}" -eq 1 ] || abort "Shell mode is only available when Gantry is invoked as a Docker container"
        bash
        ;;

    deploy|undeploy)
        [ $# -lt 1 ] && abort_with_usage

        # get the set of components to undeploy
        declare -a COMPONENTS
        FORCE=0
        NAMES_ARE_MACHINE_NAMES=0
        REGION="${DIGITAL_OCEAN_REGION}"
        while [ $# -gt 0 ]; do
            case $1 in
                all)
                    case "$MODE" in
                        deploy)
                            for COMPONENT in $(get_undeployed_component_names); do COMPONENTS+=( $COMPONENT ); done
                            ;;
                        undeploy)
                            NAMES_ARE_MACHINE_NAMES=1
                            for COMPONENT in $(get_deployed_component_names); do COMPONENTS+=( $COMPONENT ); done
                            ;;
                    esac
                    ;;
                --force)
                    FORCE=1
                    ;;
                --region)
                    REGION=$2
                    shift
                    ;;
                *)
                    COMPONENTS+=($1)
                    ;;
            esac
            shift
        done

        case "$MODE" in
            deploy)
                deploy_many --region ${REGION} ${COMPONENTS[@]} $*
                ;;
            undeploy)
                undeploy_many ${FORCE} ${NAMES_ARE_MACHINE_NAMES} ${COMPONENTS[@]}
                ;;
        esac
        ;;

    status)
        print_status
        ;;

    ssh|docker|logs|exec|ip)
        [ $# -lt 1 ] && abort_with_usage
        COMPONENT="$1"; shift
        export_component_vars "${COMPONENT}"
        IP=$(docker-machine ip ${DOCKER_MACHINE_NAME} 2>/dev/null || abort "${COMPONENT} is not deployed")

        SSH_TO_HOST=0
        [[ $# -ge 1 && "$1" == "--host" ]] && SSH_TO_HOST=1 && shift

        if [ "${MODE}" == "ip" ]; then
            echo "${IP}"
        elif [ "${MODE}" == "docker" ]; then
            docker-machine ssh ${DOCKER_MACHINE_NAME} docker $*
        elif [ "${MODE}" == "exec" ]; then
            [ "${COMPONENT}" == "routinator" ] || abort "Executing commands is not supported yet for ${COMPONENT}."
            [ $# -lt 1 ] && abort_with_usage
            docker-machine ssh ${DOCKER_MACHINE_NAME} docker exec routinator routinator $*
        elif [ "${MODE}" == "logs" ]; then
            FOLLOW=""
            DETAILED=0
            while [ $# -ge 1 ]; do
                ARG="$1"; shift
                case $ARG in
                    --follow)
                        FOLLOW="--follow"
                        ;;
                    --detailed)
                        DETAILED=1
                        ;;
                esac
            done

            export_component_vars "${COMPONENT}"
            docker-machine ssh ${DOCKER_MACHINE_NAME} docker logs ${FOLLOW} ${DOCKER_SERVICE}
        elif [[ "${COMPONENT}" == "routinator" || "${SSH_TO_HOST}" -eq 1 ]]; then
            my_log "You are about to be connected to the host Droplet on which the ${COMPONENT} Docker container runs."
            check_proceed && echo && docker-machine ssh ${DOCKER_MACHINE_NAME}
        else
            SSH_PORT=$(get_playbook_global_var router_port_external)
            my_log "You are about to be connected to the proprietary interface of router ${COMPONENT}."
            my_log "When prompted enter password: ${ROUTER_PASS}"
            check_proceed && echo && ssh -l ${ROUTER_USER} -p ${SSH_PORT} ${IP}
        fi
        ;;

    registry)
        [ $# -lt 1 ] && abort_with_usage
        case $1 in
            ls)
                reg ls -u ${DOCKER_REGISTRY_USER} -p ${DOCKER_REGISTRY_PASS} ${DOCKER_REGISTRY_FQDN}
                ;;

            rm)
                my_log "You are about to delete private Docker registry image '$2'"
                check_proceed || abort "User chose to abort."
                reg rm -u ${DOCKER_REGISTRY_USER} -p ${DOCKER_REGISTRY_PASS} ${DOCKER_REGISTRY_FQDN}/$2
                ;;

            deploy)
                cd ${BASEDIR}

                my_log "You are about to deploy a private Docker registry on a DigitalOcean droplet."
                my_log "Deployment requires a DigitalOcean account and an existing DNS domain managed by DigitalOcean".
                my_log "You are strongly advised to read the documentation about the Terraform module that will be"
                my_log "used to deploy the registry:"
                my_log
                my_log "    https://registry.terraform.io/modules/ximon18/docker-registry/digitalocean/0.0.1-alpha"
                my_log
                my_log "During deployment you will be asked some questions. Please consult the link above for help."
                my_log
                my_log "The following properties of your registry are already defined:"
                my_log
                my_log "    registry_fqdn: ${DOCKER_REGISTRY_FQDN}"
                my_log "    registry user: admin"
                my_log "    registry pass: ${DOCKER_REGISTRY_PASS}"
                my_log
                PARENT_DOMAIN=$(echo ${DOCKER_REGISTRY_FQDN} | cut -d '.' -f 2-)
                my_log "Deployment will FAIL if parent domain ${PARENT_DOMAIN} is not already delegated to your DigitalOcean account."
                check_proceed || abort "User chose to abort."

                my_log
                my_log "An SSH key pair will be created for access to the private Docker registry Droplet."
                check_proceed || abort "User chose to abort."

                if [[ ! -e ~/.ssh/id_rsa || ! -e ~/.ssh/id_rsa.pub ]]; then
                    echo "Creating SSH key pair.."
                    ssh-keygen -f ~/.ssh/id_rsa -t rsa -N '' >/dev/null
                fi
                my_log "Private Docker registry SSH key details:"
                my_log "Public key: "; cat ~/.ssh/id_rsa.pub
                my_log "Private key: "; cat ~/.ssh/id_rsa
                my_log
                my_log "Please copy these keys to a safe location."
                my_log "If you ever need to SSH into the private Docker registry Droplet you will need them!"

                my_log "Are you ready to begin the deployment process?"
                check_proceed || abort "User chose to abort."

                export TF_VAR_registry_fqdn="${DOCKER_REGISTRY_FQDN}"
                export TF_VAR_registry_admin_password="${DOCKER_REGISTRY_PASS}"
                terraform init && terraform apply

                my_log "Done."
                ;;

            publish)
                my_log "Publishing builds a vrnetlab router image and publishes it to your private Docker registry."
                my_log "The router images and licenses must be supplied by you."
                check_proceed || abort "User chose to abort."

                my_log
                my_log "Which of the following router image types do you want to publish?"
                find ${BASEDIR}/vrnetlab/ -maxdepth 1 -type d -exec test -d '{}/docker' \; -print | grep -Eo '[^/]+$' | sort | sed -e 's/^/    /'
                read -p "$(my_timestamp): Router type, e.g. sros: " PUBLISH_ROUTER_TYPE
                [[ ! -z ${PUBLISH_ROUTER_TYPE} && -d ${BASEDIR}/vrnetlab/${PUBLISH_ROUTER_TYPE} ]] || abort "Unknown router type ${PUBLISH_ROUTER_TYPE}"

                my_log
                my_log "Please copy or sym link your .qcow2 router image, and optionally a .qcow2.license file, into:"
                my_log "    ${GANTRY_BIND_MOUNT_HOST_DIR}"

                my_log
                my_log "Please read CAREFULLY the instructions that will be printed next on your screen."
                my_log "If you do not name the copied/linked files correctly the build will FAIL."
                check_proceed || abort "User chose to abort."

                my_log
                cat ${BASEDIR}/vrnetlab/${PUBLISH_ROUTER_TYPE}/README.md
                check_proceed || abort "User chose to abort."

                my_log
                pushd ${BASEDIR}/vrnetlab/${PUBLISH_ROUTER_TYPE}
                find ${GANTRY_BIND_MOUNT_GUEST_DIR} -type f -exec ln -s {} \;
                ls -la
                make docker-image
                popd

                my_log
                BUILT_IMAGE=$(docker image ls --format "{{.Repository}}:{{.Tag}}" | head -n 1)
                [ -z ${BUILT_IMAGE} ] && abort "The image build process failed."

                my_log "The image build has finished. Does the following identify the image that was built?"
                my_log "    ${BUILT_IMAGE}"
                check_proceed || abort "User chose to abort"

                docker tag ${BUILT_IMAGE} ${DOCKER_REGISTRY_FQDN}/${BUILT_IMAGE}
                docker login -u ${DOCKER_REGISTRY_USER} -p ${DOCKER_REGISTRY_PASS} ${DOCKER_REGISTRY_FQDN}
                docker push ${DOCKER_REGISTRY_FQDN}/${BUILT_IMAGE}
                docker logout

                my_log "Done."
                ;;

            *)
                abort_with_usage
                ;;
        esac
        ;;

    test)
        [ $# -lt 1 ] && abort_with_usage
        COMPONENT="$1"; shift
        PLAYBOOK_FILENAME=""
        if [ $# -ge 1 ]; then
            PLAYBOOK_FILENAME="$1"; shift
            PLAYBOOK_PATH="${GANTRY_BIND_MOUNT_GUEST_DIR}/${PLAYBOOK_FILENAME}"
            [ ! -e "${PLAYBOOK_PATH}" ] && abort "Test suite playbook file '${GANTRY_BIND_MOUNT_HOST_DIR}/${PLAYBOOK_FILENAME}' not found."
        else
            PLAYBOOK_PATH="${GANTRY_BIND_MOUNT_GUEST_DIR}/test-*.yml"
            # Replace spaces with commas - see run_playbook()
            PLAYBOOK_PATH=${PLAYBOOK_PATH// /,}
        fi

        if [ "${COMPONENT}" == "all" ]; then
            ONLY_THIS_HOST="all"
        else
            export_component_vars "${COMPONENT}"
            ONLY_THIS_HOST="${DOCKER_MACHINE_NAME}"
        fi

        run_playbook ${PLAYBOOK_PATH} ${ONLY_THIS_HOST} $*
        ;;

    debug)
        [ $# -lt 1 ] && abort_with_usage
        SUBMODE="$1"; shift
        case ${SUBMODE} in
            ansible-inventory)
                ansible-inventory -i ${INVENTORY_PLUGIN_CONFIG_FILE} $*
                ;;
            docker-machine)
                docker-machine $*
                ;;
        esac
        ;;

    help|--help)
        show_usage
        ;;

    --version)
        pushd ${BASEDIR} >/dev/null; VERSION=$(git describe --tags --long); popd >/dev/null
        echo ${VERSION}
        ;;

    *)
        abort_with_usage
        ;;
esac

exit 0