Latest changes

Makefile

@@ -36,7 +36,7 @@ clean: # Clean Project
 	rm -rf *~ docs/doxy docs/epydoc docs/pylint_*.html docs/pep8.report.txt
 
 dist/hilbert: hilbert.spec
-	pyinstaller hilbert.spec # may need to be run with a proper Python interpreter, if several are available
+	${HOME}/.local/bin/pyinstaller3 hilbert.spec # may need to be run with a proper Python interpreter, if several are available
 
 dist: setup.py
 	python3 setup.py sdist

README.md

@@ -12,43 +12,25 @@ Travis CI Build Status: [![devel](https://travis-ci.org/hilbert/hilbert-cli.svg?
 
 # General notes about shell scripts:
 
-* Exit codes may be as follows (see `status.sh`, others will be updated):
+* Exit codes may be as follows:
   * 0: success
   * 1: detected error which is not our fault (e.g. network / HW etc): user can try again
   * 2: error due to wrong usage of scripts / in config files or some assumption was violated. 
   * other positive values: something unexpected has happened.
 
 * One may need to capture both `STDOUT` and `STDERR`. Error messages (in `STDERR`) that are meant to be presented to users (admins) must be as informative as possible.
 
-# UI Back-end: high-level action scripts
-
-* `list_stations.sh`: query current YAML configuration (`hilbert list_stations --format dashboard`)
-* `start_station.sh`: start stopped station (`hilbert poweron $station_id`)
-  1. initiates station power-on (e.g. via WOL)
-* `appchange_station.sh`: switch GUI applicaiton running on the station `hilbert app_change $station_id $app_id`
-  1. switch GUI app. on the station
-* `stop_station.sh`: stop station (`hilbert poweroff $station_id`):
-  1. gracefully finish (stop / kill / remove) all running framework' services 
-  2. initiate system shutdown (with power-off) of the station (alternative: `poweroff.sh $station_id`)
-
-NOTE: rebooting the station can be done with: `shutdown.sh STATION -r now` or `reboot.sh STATION`
-
-TODOs: 
-  * `sync.sh` (to synchronize local cache `STATIONS/` with station configs & scripts from CMS). 
-  Sync. is to be performed once before front-end starts & upon request from CMS (external trigger!):
-  * `start_station.sh` will not wait for remote machine to power-on completely - there should be a wait on OMD afterwards
-  * `stop_station.sh` and `appchange_station.sh` should trigger update of OMD checks
-
 # Server-side low-level management CLI tool:
 
 ```
-usage: hilbert [-h] [-p] [-V] [-v | -q] [-H] subcommand
+usage: hilbert [-h] [-p] [-t] [-d] [-V] [-v | -q] [-H] subcommand
 
 Hilbert - server tool: loads configuration and does something using it
 
 positional arguments:
  subcommand      :
                  app_change         change station's top application
+                 app_restart        restart current/default application on a station
                  cfg_deploy         deploy station's local configuration to corresponding host
                  cfg_query          query some part of configuration. possibly dump it to a file
                  cfg_verify         verify the correctness of Hilbert Configuration .YAML file
@@ -59,50 +41,67 @@ positional arguments:
                  list_stations      list station IDs
                  poweroff           finalize Hilbert on a station and shut it down
                  poweron            wake-up/power-on/start station
+                 reboot             reboot station
+                 run_shell_cmd      run specified shell command on given station...
 
 optional arguments:
  -h, --help      show this help message and exit
  -p, --pedantic  turn on pedantic mode
+ -t, --trace     turn on remote verbose-trace mode
+ -d, --dryrun    increase dry-run mode
  -V, --version   show hilbert's version and exit
  -v, --verbose   increase verbosity
  -q, --quiet     decrease verbosity
  -H, --helpall   show detailed help and exit
-
 ```
 
 # Client-side low-level driver (accessible either locally or via SSH):
 
-
 ```
-usage: hilbert-station [-h] [-p] [-V] [-v | -q] subcommand
+usage: hilbert-station [-v|-q|-s] [-d|-D] [-t|-T] [-L] [-i|-h|-V|subcommand] [sub-arguments/options]
 
 Hilbert - client part for Linux systems
 
 positional arguments:
- subcommand:
+ subcommands:
    init [<cfg>]            init station based on given or installed configuration
    list_applications       list of (supported) applications
    list_services           list of background services
    app_change <app_id>     change the currently running top application to specified
-   start                   start Hilbert on the system
+   start [app_id]          start Hilbert on the system
    stop                    stop Hilbert on the system
    shutdown                shut down the system
 
 optional arguments:
-  -h                       show this help message and exit
-  -V                       show version info and exit
+  -h                       show this help message [+internal commands/call tree, depending on verbosity] and exit
+  -V                       show tool version [+internal info in verbose mode] and exit
+  -i                       show internal info and exit
   -v                       increase verbosity
   -q                       decrease verbosity
+  -s                       silent: minimal verbosity
   -t                       turn on BASH tracing and verbosity
   -T                       turn off BASH tracing and verbosity
   -d                       turn on dry-run mode
   -D                       turn off dry-run mode
+  -L                       disable locking (e.g. for recursive sub-calls)
 
 respected environment variables:
-  HILBERT_CONFIG_BASEDIR   location of the base configuration directory of hilbert-station. Default: '~/.config/hilbert-station'
+  HILBERT_CONFIG_BASEDIR   base configuration directory. Current: [~/.config/hilbert-station]
+  HILBERT_CONFIG_DIR       configuration directory. Current: [~/.config/hilbert-station/configs]
+  HILBERT_CONFIG_FILE      station config file. Current: [station.cfg]
+
+currently detected hilbert variables/values: 
+  HILBERT_SERVER_CONFIG_PATH: ...
+  HILBERT_CONFIG_BACKUP: ~/.config/hilbert-station/config_backup
+  HILBERT_SHUTDOWN_DELAY: 1s
+  HILBERT_LOCKFILE_DIR: /var/run/hilbert
+  HILBERT_STATION: .../bin/hilbert-station
 ```
 
 NOTE: all commands (except `init <cfg>` / `shutdown` / `-h` / `-V`) require station's configuration to be present
 
+
 ## License
 This project is licensed under the [Apache v2 license](LICENSE). See also [Notice](NOTICE).
+
+

docs/HOWTO.md

@@ -0,0 +1,180 @@
+# How-To guides for Hilbert system
+
+Note: on a server "${HILBERT_SERVER_CONFIG_PATH}" should be equal to "/shared/interactives/0000_general/Hilbert/CFG/"
+
+## Add a new PC into a hilbert setup
+
+1. fix a DNS name (KIOSK_ADDRESS) for a new station (e.g. `kiosk023XXX.ads.eso.org`)
+2. decide on proper <STATION_ID> for it (according to the following schema: `client_[0-9][0-9][0-9][0-9](_[0-9])?`)
+3. depending on its HW decide on corresponding profile (i.e. set of services) to run on PC by default
+4. add it into OMD (see below)
+5. add it into `/shared/interactives/0000_general/Hilbert/CFG/Hilbert.yml` configuration
+   * by analogy with existing stations but with its own unique networking and MAC addresses!
+6. restart the Dashboard
+
+## Add a station into OMD
+
+Note: OMD Login credentials are present in other document with secrets
+
+Let us add a station with ID: `<STATION_ID>` and network address: `<KIOSK_ADDRESS>`
+
+NOTE: make sure that station is running Hilbert already (in order to discover all available CheckMK services on it) 
+
+Create new host entry via: http://es-ex.hq.eso.org/default/check_mk/wato.py?mode=newhost&folder=
+
+1. `Hostname` set to be `<STATION_ID>`
+2. check `IP address` and set input field to be `<KIOSK_ADDRESS>`
+3. press bottom-left button: "Save and go to serrvices"
+4. on "Services of host `<STATION_ID>` (might be cached data)" there should be around 20 services (most of them should be green)
+5. press button "Automatic Refresh (Tabula Rasa)"
+
+After you are done adding all stations go to top button "... Changes": http://es-ex.hq.eso.org/default/check_mk/wato.py?mode=changelog&folder=
+and press button "Activate Changes!"
+
+Result should be:
+
+```
+Progress	Status
+OK              Configuration successfully activated.
+```
+
+## Check Hilbert configuration and docker-compose files
+
+Run the following on your current server:
+```
+$ cd /shared/interactives/0000_general/Hilbert/CFG
+$ ./check_cfg.sh
+```
+
+## Deployment of Hilbert configuration to specified station (or refresh/update Hilbert there)
+
+Run the following on your current server:
+```
+$ cd /shared/interactives/0000_general/Hilbert/CFG
+$ ./hilbert cfg_deploy <STATION_ID>
+```
+
+Note: on remote station Hilbert configuration will by installed under `~/.config/hilbert-station/` by default. 
+Only Hilbert client-side CLI tool `hilbert-station` is supposed to work with it.
+
+
+## Cleanup remote station
+
+Run the following on your current server:
+
+```
+$ cd /shared/interactives/0000_general/Hilbert/CFG
+$ ./hilbert cleanup <STATION_ID>
+```
+
+Alternatively after logging-in to corresponding host (via `hilbert-ssh <STATION_ID>` or `ssh <KIOSK_ADDRESS>`) via ssh run the following:
+```
+$ hilbert-station cleanup # or
+$ hilbert-station cleanup --force # if Hilbert is currently running
+```
+
+
+
+## Hilbert client-side CLI tool: `hilbert-station`
+
+```
+usage: hilbert-station [-v|-q|-s] [-d|-D] [-t|-T] [-L] [-i|-h|-V|subcommand] [sub-arguments/options]
+
+Hilbert - client part for Linux systems
+
+positional arguments:
+ subcommands:
+   init [<cfg>]             init station based on given or installed configuration
+   list_applications        list of (supported) applications
+   list_services            list of background services
+   app_change <app_id>      change the currently running top application to specified
+   app_restart              restart the currently running top application
+   start [<app_id>]         start Hilbert on the system
+   pause                    pause Hilbert on the system
+   stop                     stop Hilbert on the system
+   shutdown [now]           shut down the system
+   reboot [now]             reboot the system
+   cleanup [--force]        local system cleanup (identical to docker_cleanup on Linux host)
+   docker_cleanup [--force] total cleanup of local docker engine (images, data volumes)
+
+optional arguments:
+  -h                       show this help message [+internal commands/call tree, depending on verbosity] and exit
+  -V                       show tool version [+internal info in verbose mode] and exit
+  -i                       show internal info and exit
+  -v                       increase verbosity
+  -q                       decrease verbosity
+  -s                       silent: minimal verbosity
+  -t                       turn on BASH tracing and verbosity
+  -T                       turn off BASH tracing and verbosity
+  -d                       turn on dry-run mode
+  -D                       turn off dry-run mode
+  -L                       disable locking (e.g. for recursive sub-calls)
+```
+
+Note: `hilbert-station` is a bash script installed on station via `hilbert-cli-*.rpm`.
+Its source is available at https://github.com/hilbert/hilbert-cli/ (in `tools/hilbert-station`)
+
+
+
+## Hilbert server-side CLI tool
+
+```
+$ hilbert
+usage: hilbert [-h] [-p] [-t] [-d] [-V] [-v | -q] [-H] subcommand
+
+Hilbert - server tool: loads configuration and does something using it
+
+positional arguments:
+ subcommand      :
+                 app_change         change station's top application
+                 app_restart        restart current/default application on a station
+                 cfg_deploy         deploy station's local configuration to corresponding host
+                 cfg_query          query some part of configuration. possibly dump it to a file
+                 cfg_verify         verify the correctness of Hilbert Configuration .YAML file
+                 cleanup            perform system cleanup on remote station
+                 list_applications  list application IDs
+                 list_groups        list (named) group IDs
+                 list_profiles      list profile IDs
+                 list_services      list service IDs
+                 list_stations      list station IDs
+                 poweroff           finalize Hilbert on a station and shut it down
+                 poweron            wake-up/power-on/start station
+                 reboot             reboot station
+                 run_shell_cmd      run specified shell command on given station...
+
+optional arguments:
+ -h, --help      show this help message and exit
+ -p, --pedantic  turn on pedantic mode
+ -t, --trace     turn on remote verbose-trace mode
+ -d, --dryrun    increase dry-run mode
+ -V, --version   show hilbert's version and exit
+ -v, --verbose   increase verbosity
+ -q, --quiet     decrease verbosity
+ -H, --helpall   show detailed help and exit
+```
+
+Run `hilbert -H` for detailed information on all commands
+
+Note: `hilbert` is a CLI packaged Python script. Its sources are available at https://github.com/hilbert/hilbert-cli
+
+
+## Hilbert Data/Configuration Restoration for a server
+
+See also `/shared/server.backup_restore/README.md` for more details
+
+Note: the procedure will take quite a long time therefore it is better to run it 
+within some terminal multiplexer (e.g. `screen` or `tmux`) so that it will not be interrupted 
+if your connection to server is cut. 
+
+Suggested procedure:
+
+1. login as `kiosk` user to new (empty) server
+2. check that NFS mounted disk `/shared` is present
+3. run `tmux` (or `screen`): should start another shell line, where you run the following command:
+4. run `/shared/server.backup_restore/bin/restore.sh`
+
+NOTE: Please do not use `Ctrl+C` to exit. 
+Use `Crtl+b d` or `Ctrl+a d` to detach from multiplexer session. 
+Later on you can attach back to previous session with `tmux at` after logging to the server.
+
+NOTE: do not use `root` for restoration!

hilbert_config/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import absolute_import
 from __future__ import unicode_literals
 
-__version__ = '0.3.0'  # TODO: add git commit id?
+__version__ = '0.4.0'  # TODO: add git commit id?
 
 # from hilbert_cli_config import *