Difference between revisions of "Dino"

From Bicom Systems Wiki

m (Flag Options)
m (Blanked the page)
 
Line 1: Line 1:
=Introduction=
 
  
BSSUP is Bicom Systems' support SSH certificate authority access tool. The BSSUP is using certificate authority to authenticate servers and clients. It is specifically designed for using on SERVERware 3, both standalone and cluster edition.
 
 
The main purpose of BSSUP is that Bicom Systems' support can have secure and undisturbed (no need for passwords or other methods of authentication) SSH access to client's machines, but only when client requests it. Only clients have option to open SSH access and also specify for how long it will stay open.
 
 
This daemon will be installed on client's machines. Upon first running, it will try to download Bicom Systems' SSH Certificate Authority public key, if download fails, program will terminate.
 
 
After successful download of Bicom Systems' SSH Certificate Authority public key, that key will be used for authenticating incoming connection requests on client's machines. SSH access will only be allowed to those who have SSH certificate which was signed by corresponding private key to Bicom Systems' SSH Certificate Authority public key. Only authorized staff will have access to Bicom Systems' SSH Certificate Authority private key.
 
 
The BSSUP daemon comes with GUI for opening/closing SSH access and monitoring established SSH connections and with REST API. It also comes with sw-ls tool which prints out SERVERware cluster topology.
 
 
=Requirements=
 
 
* SERVERware 3
 
* Go tool chain
 
* Go workspace (screencast)
 
 
=Building from Source=
 
 
Run your desired SERVERware 3 host and go to '''src''' folder of Go workspace, download and extract the project there and open project folder.
 
 
  # make
 
  # sh build_package.sh
 
  # scp -P2222 build/bssup.tbz2.sh  root@*ip_address_of_your_controller*:/
 
  # scp -P2020 build/bssup.tbz2.sh  root@*ip_address_of_your_host*:/
 
 
Repeat the last command for all hosts on which you want to install BSSUP.
 
 
===Install on CONTROLLER===
 
 
  # lxc-attach -n CONTROLLER
 
  # cd /
 
  # sh bssup.tbz2.sh
 
 
===Install on HOST===
 
 
Connect to your host and run following commands:
 
 
  # cd /
 
  # sh bssup.tbz2.sh
 
 
[http://asciinema.org/a/Ns8mRWREztbzOM47wYITaQf06?autoplay=1 <span style="color: red;">'''Build and install example'''</span>]
 
 
=Usage=
 
 
'''Config Files'''
 
 
Initially, there are two config files: '''etc/bssup.json.controller''' and '''etc/bssup.json.host''', which you can see in etc directory. During installation, script will determine whether BSSUP is being installed on '''CONTROLLER''' or on '''host''', based on that, it will rename matching config file into '''bssup.json''', and remove the other config file to avoid any confusion. Two config files are necessary because of specific options which need to be set only on '''CONTROLLER''' or on '''host''', e.g. options '''http''' and '''timeout''' are specified only on '''CONTROLLER''', while option '''dyncaurl''' is specified only on '''host'''. You can, at any time, change these config files and restart the BSSUP daemon for changes to take place.
 
 
==Starting Daemon==
 
 
===Controller===
 
 
In '''/opt/bssup/etc/bssup.json''' you can configure how to start bssup daemon (see example).
 
 
In '''/opt/bssup/etc/bssup.conf''' you can set path for your own config file, note that it must be JSON formatted.
 
 
  # ./etc/init.d/bssupd [start/status/stop]
 
 
===HOST===
 
 
In '''/opt/bssup/etc/bssup.json''' you can configure how to start bssup daemon (see example).
 
 
In '''/opt/bssup/etc/bssup.conf''' you can set path for your own config file, note that it must be JSON formatted.
 
 
  # ./etc/init.d/bssupd [start/status/stop]
 
 
==Flag Options==
 
 
'''Note''': ''All flags must be specified in /opt/bssup/etc/bssup.json file, because daemon is started using init.d script.''
 
 
* '''-ca''' : string. A filepath to SSH CA public key used for authenticating certificates on incoming connection requests. Defaults to /home/user/.ssh/ssh_ca_bicoms.pub.
 
 
* '''-caurl''' : string. Specify from where to download Bicom Systems' CA public key.
 
 
* '''-config''' : string. A filepath to config file used for starting daemon. Defaults to /etc/bssup.json.
 
 
* '''-debug''' : boolean. Show verbose/debug output. Defaults to false.
 
 
* '''-dyncaurl''' : boolean. Watch CONTROLLER's IP address in /etc/serverware/sw.conf file and update CA URL for public key download on it's change. '''Note''': ''This is set to true only when the daemon is being started on hosts. When dyncaurl flag is specified, waitpubk option is also set to true.''
 
 
* '''-h''' -help : boolean. Outputs flag usage.
 
 
* '''-host''' : string. Listening interface for SSH server. Defaults to 0.0.0.0.
 
 
* '''-http''' : string. IP address and port for starting http server (e.g. -http 0.0.0.0:1234 or -http :1234).
 
 
* '''-keyfile''' : string. A filepath to host's SSH private key. Defaults to /etc/ssh/ssh_host_rsa_key.
 
 
* '''-log''' : string. Specify where to output logs, [backend]://. Backend: stdout, syslog, file, mysql. See [http://tuzla-git.local/asmirselimovic/bssup/src/master/log/README.md README.md] in bssup/log for detailed instructions. (default "syslog://")
 
 
* '''-p -port''' : string. Listening port for SSH server. Defaults to 22, then fallsback to 2200.
 
 
* '''-pidfile''' : string. Path to a PID file.
 
 
* '''-timeout''' : int. Timeout for SSH server in seconds. Defaults to 1 day.
 
 
* '''-version''' : boolean. Outputs daemon version.
 
 
* '''-verifypubk''' : string. A filepath to directory with public keys used for verification. Download CA public key and signature and verify downloaded CA public key using that signature.
 
 
'''Note''': When you start daemon with -verifypubk flag:
 
 
* if there is a public key already downloaded, daemon will try to download a new key and signature, if it fails, there will be a warning that key hasn't been updated, or verified, and the program will continue
 
* if there isn't a public key downloaded, daemon will try to download it until it succeeds, or someone kills daemon process
 
* when daemon is started without -verifypubk flag, if there is any error during download program will terminate
 
* verifypubk is an option for starting daemon in CONTROLLER mode, there is no need to download signature and verify the key when downloading CA public key on host
 
 
* '''-waitpubk''' : boolean. Retry download of Bicom's CA public key.
 
 
'''Note''': When you start daemon with -waitpubk flag:
 
* if there is a public key already downloaded, daemon will try to download a new key, if it fails, there will be a warning that key hasn't been updated and the program will continue,
 
* if there isn't a public key downloaded, daemon will try to download it until it succeeds, or someone kills daemon process ,
 
* when daemon is started without -waitpubk flag, if there is any error during download program will terminate.
 
 
==Config File Example==
 
 
  {
 
  "sshhost" : "0.0.0.0",
 
  "sshport" : "4000",
 
  "SSHTimeout" : 86400,
 
      "httpaddress" : "0.0.0.0:2234",
 
  "debug" : true,
 
      "caurl" : <nowiki>https://downloads.bicomsystems.com/serverware3/ssh_ca_bicoms.pub</nowiki>"
 
  }
 
 
==REST API==
 
 
REST API can only be used when HTTP server is started. Using REST API you can get information whether SSH access is open, you can open and close SSH access, see currently active sessions on SSH server and close active sessions. On every made request, server responds with a HTTP status code and an appropriate message. All responses are in JSON format.
 
 
===Get SSH access status===
 
 
Request:
 
 
  GET <nowiki>https://serveraddress/api/bssup/status</nowiki>
 
 
Response:
 
 
  {
 
  "status": "[open/closed]",
 
  "port": "[portValue]",
 
  "remainingtime": "Mon DD, YYYY HH:MM:SS"
 
  }
 
 
===Open SSH Access===
 
 
Request:
 
 
  POST <nowiki>https://serveraddress/api/bssup/open</nowiki>
 
 
Params:
 
 
  {
 
  "port": "[portValue]",
 
  "status": "open",
 
  "timeout": [0/timeoutInSeconds]
 
  }
 
 
Response:
 
 
  {
 
  "message": "",
 
  "code": httpStatusCode
 
  }
 
 
===Close SSH Access===
 
 
Request:
 
 
  POST <nowiki>https://serveraddress/api/bssup/close</nowiki>
 
 
Response:
 
 
  {
 
  "message": "message",
 
  "code": httpStatusCode
 
  }
 
 
===Get Active Sessions===
 
 
Get active sessions
 
 
Request:
 
 
  GET <nowiki>https://serveraddress/api/bssup/sessions</nowiki>
 
 
Response:
 
 
  [
 
  {
 
  "id": "sessionUUID",
 
  "srcip": "sourceIP",
 
  "srcport": sourcePort,
 
  "sessiontimeout": "Mon DD, YYYY HH:MM:SS",
 
  "sessionstarted": "Mon DD, YYYY HH:MM:SS"
 
  }
 
  ]
 
 
===Close Active Sessions===
 
 
Request:
 
 
  PUT <nowiki>https://serveraddress/api/bssup/{connId}/close</nowiki>
 
 
Response:
 
 
  {
 
  "message": "message",
 
  "code": httpStatusCode
 
  }
 
 
===Get logs from database===
 
 
Request:
 
 
  GET <nowiki>https://serveraddress/api/bssup/logs</nowiki>
 
 
Response:
 
 
  [
 
  {
 
  "id": "logID",
 
  "severity": "[INFO/ERROR/DEBUG/WARN/FATAL/PANIC]",
 
  "time": date/time,
 
  "message": "someMessage"
 
  }
 
  ]
 
 
=SW-LS=
 
 
'''sw-ls''' is a tool which prints out '''SERVERware''' cluster topology.
 
 
Information which will be printed:
 
 
  HOSTname <role> <IP address>
 
      |
 
      ----- VPSname <status> <IP address>
 
 
* if tool is started with -r flag, all hosts and their respective VPSes are printed out. Note: if host doesn't have any VPS, his informations won't be printed.
 
* if started without -r flag only hosts are printed out.
 
* if it is started with name of the host given on stdin, only information about VPSes of the host with given name will be printed out.
 
 
[http://asciinema.org/a/BTR7dqp1c6DmoRNMVeGru6lmV?autoplay=1 <span style="color: red;">'''SW-LS usage example'''</span>]
 
 
=Support=
 
 
If you have any further questions that you cannot find the answer to here, or if you need any further assistance, please do not hesitate to contact asmir@bicomsystems.com.
 

Latest revision as of 16:30, 16 December 2019