docs: add gogo usage guide

README.md

@@ -5,4 +5,176 @@ Maintenance application for quick access, check and resolve issues VM/DCImanager
 ### In progress
 
 
-### See [CONTRIBUTING.md](CONTRIBUTING.md) for a general overview of how to contribute 
+### See [CONTRIBUTING.md](CONTRIBUTING.md) for a general overview of how to contribute
+
+
+
+## How to use gogo companion:
+
+
+#### Dependencies
+
+ОС: Linux, Mac, Windows
+Shell: bash
+
+
+#### Installation
+
+- download or copy the script from the root of the repository `/scripts/gogo/gogo.sh`
+- to call the script without specifying the full path, put it in the directory that is in $PATH (in the future, I assume that you will have it `~/.local/bin/`)
+
+```console
+curl https://git.isptech.ru/ISPsystem/isp-maintenance/raw/branch/main/scripts/gogo/gogo.sh -o ~/.local/bin/gogo && chmod u+x ~/.local/bin/gogo
+```
+
+#### Configuration
+
+For the script to work, you need a configuration file with settings `~/.config/gogo/gogo.conf`
+
+This config contains the following fields that are read every time you start
+
+```
+GO_SERVER_ADDR_RUSSIAN=
+GO_SERVER_ADDR_GERMANY=
+GO_SERVER_ADDR_TEST=
+VAULT_SERVER_ADDR=
+SSH_PRIVATE_KEY_USER=
+SSH_PRIVATE_KEY_PATH=
+SSH_PUBLIC_KEY_PATH=
+SSH_CRT_FILE=
+MGRCTL_IMAGE=mois3y/mgrctl:latest
+DEBUG_MODE=false
+```
+
+Please fill in the fields with current data, write the path to the keys and certificate in full `/home/username/.ssh/id_ecdsa` and so on.
+For security reasons, server addresses and paths to keys are not indicated here.
+
+For your convenience, the config can be filled out interactively
+
+```console
+gogo --init
+```
+
+
+#### Usage
+
+- Get a temporary ssh certificate
+
+```console
+gogo --crt
+```
+
+- Check your connection to test servers in both locations
+
+```console
+gogo --test
+```
+
+- If the connection is successful, you can use the script. You are beautiful!
+
+
+#### Examples
+
+- Connect to BILLmanager 6 via ssh port 22 and interface port 443
+
+```console
+gogo --bill my.example.com
+```
+or
+```console
+gogo --bill my.example.com -p 22 -wp 443
+```
+
+- Connect to BILLmanager 6 again without generating an access key to the interface
+
+```console
+gogo --bill my.example.com --ssh
+```
+
+- Connect to DNSmanager 6 via ssh port 22 and interface port 1501
+
+```console
+gogo --dns my.example.com -p 22 -wp 1501
+```
+
+- Connect to DCImanager 6 via ssh port 2222 and interface 443 port
+
+```console
+gogo --dci vm.example.com -p 2222
+```
+
+- Connect to VMmanager 6 via ssh port 2222 and interface port 443
+
+```console
+gogo --vm 228.228.228.228 -p 2222
+```
+
+- Connect to VMmanager 6 via ssh port 22 and interface port 443, indicating the id of a specific user and generate 3 keys
+
+```console
+gogo --vm vm.example.com --mgrctl auth user access --id 1488 --count 1
+```
+
+- The same thing, just print the command that is executed on the server side into the console, you can run it later simply by copying it
+
+```console
+gogo --vm vm.example.com --tty --mgrctl auth user access --id 1488 --count 1
+```
+
+
+Connect to VMmanager 6 via ssh port 22 and interface port 443 via DE go3 server
+
+```console
+gogo --vm vm.example.com -p 22 --de
+```
+
+Connect to DCImanager 6 via ssh port 22 and interface port 443 via the old go method
+
+```console
+gogo --dci dci.example.com -p 22 --go
+```
+
+##### There are also examples in `help`
+
+```console
+gogo --help
+
+Usage: gogo [options [parameters]]
+
+Examples:
+
+gogo --init | init config file
+gogo --crt  | get ssh certificate for go3 connections
+gogo --test | check go3 connection availability
+
+gogo --bill my.example.com
+gogo --vm my.example.com --de  | connect throw DE go3 server
+gogo --vm 0.0.0.0 --ssh | only ssh access
+gogo --vm 0.0.0.0 --tty | use mgrctl interactive
+
+gogo --dci 0.0.0.0 --mgrctl auth user access --id 3 --count 5
+gogo --dci 0.0.0.0 --mgrctl auth user ls --admins
+gogo --vm 0.0.0.0 --port 22122 --mgrctl auth user ls --admins
+gogo --vm 0.0.0.0 --tty --mgrctl auth user ls --admins
+gogo --dns ns1.example.com --web-port 1501
+gogo --dns ns1.example.com --port 22122 --web-port 1501
+gogo --bill my.example.com --port 22 --web-port 1501
+
+Options:
+
+ --vm[dci|bill|dns|ip] expected ip_addr             required
+ --port     | -p    ssh port,   default 22
+ --web-port | -wp   web port,   default 443
+ --go/--go3         go version, default go3
+ --de               connect throw DE go3 server
+ --ssh              open only ssh session
+ --tty              for vm6/dci6 echo cmd for run container
+ --mgrctl [args]    for vm6/dci6 customize access params
+
+Single options:
+ --init     | -i    generate configuration
+ --crt      | -c    generate ssh cert
+ --test     | -t    check go3 connection availability
+ --version  | -v    print version
+ --help     | -h    print this message and exit
+```

mgrctl/api/base.py

@@ -7,6 +7,7 @@ import requests
 from time import sleep
 
 from mgrctl.settings.api import (
+    API_INPUT_PORT,
     API_URL,
     API_HEADERS,
     API_EMAIL,
@@ -14,6 +15,7 @@ from mgrctl.settings.api import (
     API_VERIFY_SSL,
     API_COUNT_TRY_CONNECTIONS
 )
+from mgrctl.settings.platform import PLATFORM_TYPE
 
 
 class BaseAPI(object):
@@ -33,6 +35,7 @@ class BaseAPI(object):
     def call_api(self, url, method='GET', headers={}, data={}):
         attempt = API_COUNT_TRY_CONNECTIONS
         while attempt:
+            attempt -= 1
             try:
                 uri = self._gen_request_url(url)
                 headers = self.API_HEADERS if not headers else headers
@@ -52,16 +55,25 @@ class BaseAPI(object):
                         verify=self.API_VERIFY_SSL
                     )
             except Exception as error:
-                click.echo(f'Error: {type(error).__name__}')
+                ConnectionError = requests.exceptions.ConnectionError
-                sys.exit()
+                if type(error) is ConnectionError and PLATFORM_TYPE == 'dci':
+                    # ? workaround if new docker version use dashes
+                    # TODO: ISPsystem developers must set container_name !!!
+                    self.API_URL = f'http://dci-input-1:{API_INPUT_PORT}'
+                    if attempt == 0:
+                        click.echo(f'Error: {type(error).__name__}')
+                        sys.exit()
+                    else:
+                        continue
+                else:
+                    click.echo(f'Error: {type(error).__name__}')
+                    sys.exit()
 
             # Get response:
             response = self._parse_response(api_request)
 
             # Validate response:
             if self._error_handler(response):
-                attempt -= 1
-                sleep(2)  # wait 2 second timeout
                 continue  # new attempt connection
 
             return response
@@ -80,6 +92,7 @@ class BaseAPI(object):
 
     def _is_error_3004(self, error):
         if error.get('code') == 3004:
+            sleep(2)  # wait 2 second timeout
             return True
 
     def _error_handler(self, response):

scripts/gogo/gogo.sh

@@ -5,8 +5,8 @@
 # -- -- -- -- -- --
 
 # INIT GLOBAL VARIABLES:
-_VERSION="0.1.0"
+_VERSION="0.1.1"
-_SCRIPT_NAME="$0"
+_SCRIPT_NAME="$(basename $0)"
 _GO_CMD="go3"
 _DEBUG_MODE=false
 
@@ -61,38 +61,44 @@ help() {
 	local script=$(colorize GREEN "$_SCRIPT_NAME")
 	local required=$(colorize RED "required")
 	# help message
-	printf "Usage: $script [options [parameters]]                         \n"
+	printf "Usage: $script [options [parameters]]                              \n"
-	printf "                                                              \n"
+	printf "                                                                   \n"
-	printf "Examples:                                                     \n"
+	printf "Examples:                                                          \n"
-	printf "                                                              \n"
+	printf "                                                                   \n"
-	printf "./gogo.sh --init | init config file                           \n"
+	printf "${script} --init | init config file                                \n"
-	printf "./gogo.sh --crt  | get ssh certificate for go3 connections    \n"
+	printf "${script} --crt  | get ssh certificate for go3 connections         \n"
-	printf "                                                              \n"
+	printf "${script} --test | check go3 connection availability               \n"
-	printf "./gogo.sh --bill my.example.com                               \n"
+	printf "                                                                   \n"
-	printf "./gogo.sh --vm 0.0.0.0 --ssh | only ssh access                \n"
+	printf "${script} --bill my.example.com                                    \n"
-	printf "./gogo.sh --vm 0.0.0.0 --tty | use mgrctl interactive         \n"
+	printf "${script} --vm my.example.com --de  | connect throw DE go3 server  \n"
-	printf "                                                              \n"
+	printf "${script} --vm 0.0.0.0 --ssh | only ssh access                     \n"
-	printf "./gogo.sh --dci 0.0.0.0 --mgrctl user access --id 3 --count 5 \n"
+	printf "${script} --vm 0.0.0.0 --tty | use mgrctl interactive              \n"
-	printf "./gogo.sh --dci 0.0.0.0 --mgrctl user ls --admins             \n"
+	printf "                                                                   \n"
-	printf "./gogo.sh --dci 0.0.0.0 --mgrctl user --help                  \n"
+	printf "${script} --dci 0.0.0.0 --mgrctl auth user access --id 3 --count 5 \n"
-	printf "./gogo.sh --vm 0.0.0.0 --port 22122 --mgrctl user ls --admins \n"
+	printf "${script} --dci 0.0.0.0 --mgrctl auth user ls --admins             \n"
-	printf "./gogo.sh --dns ns1.example.com --web-port 1501               \n"
+	printf "${script} --vm 0.0.0.0 --port 22122 --mgrctl auth user ls --admins \n"
-	printf "./gogo.sh --dns ns1.example.com --port 22122 --web-port 1501  \n"
+	printf "${script} --vm 0.0.0.0 --tty --mgrctl auth user ls --admins        \n"
-	printf "./gogo.sh --bill my.example.com --port 22 --web-port 1501     \n"
+	printf "${script} --dns ns1.example.com --web-port 1501                    \n"
-	printf "                                                              \n"
+	printf "${script} --dns ns1.example.com --port 22122 --web-port 1501       \n"
-	printf "Options:                                                      \n"
+	printf "${script} --bill my.example.com --port 22 --web-port 1501          \n"
-	printf "                                                              \n"
+	printf "                                                                   \n"
-	printf " --vm[dci|bill|dns|ip] expected ip_addr             $required \n"
+	printf "Options:                                                           \n"
-	printf " --port     | -p       ssh port,   default 22                 \n"
+	printf "                                                                   \n"
-	printf " --web-port | -wp      web port,   default 443                \n"
+	printf " --vm[dci|bill|dns|ip] expected ip_addr             $required      \n"
-	printf " --go/--go3            go version, default go3                \n"
+	printf " --port     | -p    ssh port,   default 22                         \n"
-	printf " --tty                 for vm6/dci6 echo cmd for run container\n"
+	printf " --web-port | -wp   web port,   default 443                        \n"
-	printf " --mgrctl [args]       for vm6/dci6 customize access params   \n"
+	printf " --go/--go3         go version, default go3                        \n"
-	printf "                                                              \n"
+	printf " --de               connect throw DE go3 server                    \n"
-	printf " --init     | -i  generate configuration                      \n"
+	printf " --ssh              open only ssh session                          \n"
-	printf " --crt      | -c  generate ssh cert                           \n"
+	printf " --tty              for vm6/dci6 echo cmd for run container        \n"
-	printf " --version  | -v  print version                               \n"
+	printf " --mgrctl [args]    for vm6/dci6 customize access params           \n"
-	printf " --help     | -h  print this message and exit                 \n"
+	printf "                                                                   \n"
+	printf "Single options:                                                    \n"
+	printf " --init     | -i    generate configuration                         \n"
+	printf " --crt      | -c    generate ssh cert                              \n"
+	printf " --test     | -t    check go3 connection availability              \n"
+	printf " --version  | -v    print version                                  \n"
+	printf " --help     | -h    print this message and exit                    \n"
 }
 
 # Ask confirmation user if No - exit with 1 state
@@ -104,17 +110,19 @@ continue_handler() {
 # Init script configuration file:
 init_config() {
 	# Lables:
-	local warning=$(colorize RED "WARNING! ")
+	local warning=$(colorize RED "WARNING!")
-	local success=$(colorize GREEN "SUCCESS! ")
+	local success=$(colorize GREEN "SUCCESS!")
 	local script_name=$(colorize GREEN "${_SCRIPT_NAME}")
 	# check if config file exists:
 	if [ -f $_CONFIG ]; then
-		echo "${warning}: Config file is already exists"
+		echo "${warning} Config file is already exists"
 		echo "New initialization rewrites current config"
 		continue_handler
 	fi
 	# get user unputs:
-	read -p "Enter go server address: "            _GO_SERVER_ADDR
+	read -p "Enter russian go server address: "    _GO_SERVER_ADDR_RUSSIAN
+	read -p "Enter germany go server address: "    _GO_SERVER_ADDR_GERMANY
+	read -p "Enter test go server address: "       _GO_SERVER_ADDR_TEST
 	read -p "Enter vault server address: "         _VAULT_SERVER_ADDR
 	read -p "Enter username: "                     _SSH_PRIVATE_KEY_USER
 	read -p "Enter full path to ssh private key: " _SSH_PRIVATE_KEY_PATH
@@ -124,7 +132,9 @@ init_config() {
 	# save config:
 	mkdir -p $_CONFIG_DIR
 	cat << EOF > "${_CONFIG}"
-GO_SERVER_ADDR=$_GO_SERVER_ADDR
+GO_SERVER_ADDR_RUSSIAN=$_GO_SERVER_ADDR_RUSSIAN
+GO_SERVER_ADDR_GERMANY=$_GO_SERVER_ADDR_GERMANY
+GO_SERVER_ADDR_TEST=$_GO_SERVER_ADDR_TEST
 VAULT_SERVER_ADDR=$_VAULT_SERVER_ADDR
 SSH_PRIVATE_KEY_USER=$_SSH_PRIVATE_KEY_USER
 SSH_PRIVATE_KEY_PATH=$_SSH_PRIVATE_KEY_PATH
@@ -133,7 +143,9 @@ SSH_CRT_FILE=$_SSH_CRT_FILE
 MGRCTL_IMAGE=$_MGRCTL_IMAGE
 DEBUG_MODE=false
 EOF
-	echo "${success}: Config file was created, run ${script_name} again"
+	echo ""
+	echo "${success} Config file was created, run ${script_name} again"
+	echo ""
 }
 
 
@@ -153,10 +165,17 @@ load_config() {
 	
 	while IFS="=" read -r key value; do
 		case "$key" in
-			"GO_SERVER_ADDR") 
+			"GO_SERVER_ADDR_RUSSIAN")
+				_GO_SERVER_ADDR_RUSSIAN="$value"
 				_GO_SERVER_ADDR="$value"
 				;;
-			"VAULT_SERVER_ADDR") 
+			"GO_SERVER_ADDR_GERMANY")
+				_GO_SERVER_ADDR_GERMANY="$value"
+				;;
+			"GO_SERVER_ADDR_TEST")
+				_GO_SERVER_ADDR_TEST="$value"
+				;;
+			"VAULT_SERVER_ADDR")
 				_VAULT_SERVER_ADDR="$value"
 				;;
 			"SSH_PRIVATE_KEY_USER")
@@ -373,7 +392,25 @@ set_ssh_agent() {
 renewal_crt() {
 	export VAULT_ADDR=$_VAULT_SERVER_ADDR
 	get_vault_crt $_VAULT_SSH_PUBLIC_KEY $_SSH_CRT_FILE
-	set_ssh_agent $SSH_PRIVATE_KEY_PATH
+	set_ssh_agent $_SSH_PRIVATE_KEY_PATH
+}
+
+
+test_go3_connection() {
+	# force only ssh connections without platform features:
+	_IS_SSH_ONLY=true
+	# set fake client address:
+	_PLATFORM_IP_ADDR="${_GO_SERVER_ADDR_TEST}"
+	_PLATFORM_SSH_PORT=22
+
+	echo "Run TEST: $_GO_SERVER_ADDR_RUSSIAN connection"
+	get_access
+
+	echo "-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --"
+
+	echo "Run TEST: $_GO_SERVER_ADDR_GERMANY connection"
+	_GO_SERVER_ADDR="${_GO_SERVER_ADDR_GERMANY}"
+	get_access
 }
 
 
@@ -386,6 +423,13 @@ optparser() {
 		help
 		exit 2
 	fi
+	# run init config if flag --init and exit:
+	if [[ "$1" == "--init" ]]; then
+		init_config
+		exit 0
+	fi
+	# load config from config file:
+	load_config
 	# parse opts:
 	while [ ! -z "$1" ]; do
 		case "$1" in
@@ -410,6 +454,9 @@ optparser() {
 			--go|--go3)
 				_GO_CMD=$(sed 's~[^[:alnum:]/]\+~~g' <<< "$1")
 				;;
+			--de)
+				_GO_SERVER_ADDR="${_GO_SERVER_ADDR_GERMANY}"
+				;;
 			--mgrctl|--tty|--ssh)
 				if [[ "$1" == "--mgrctl" ]]; then
 					_IS_MGRCTL_ARGS=true
@@ -426,14 +473,14 @@ optparser() {
 					_IS_SSH_ONLY=true
 				fi
 				;;
-			--init|-i)
-				init_config
-				exit 0
-				;;
 			--crt|-c)
 				renewal_crt
 				exit 0
 				;;
+			--test|-t)
+				test_go3_connection
+				exit 0
+				;;
 			--help|-h)
 				help
 				exit 0
@@ -456,7 +503,6 @@ optparser() {
 
 # Entrypoint:
 main() {
-	load_config
 	optparser $@
 	get_access
 }