Difference between revisions of "Dino"

From Bicom Systems Wiki

m (REST API)
m (Install on HOST)
Line 40: Line 40:
 
   # cd /
 
   # cd /
 
   # sh bssup.tbz2.sh
 
   # sh bssup.tbz2.sh
 +
 +
[http://asciinema.org/a/Ns8mRWREztbzOM47wYITaQf06?autoplay=1 <span style="color: red;">'''Build and install example'''</span>]
  
 
=Usage=
 
=Usage=

Revision as of 08:53, 3 September 2018

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

Build and install example

Usage

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 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.
  • -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" : https://downloads.bicomsystems.com/serverware3/ssh_ca_bicoms.pub"
 }

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 https://serveraddress/api/bssup/status

Response:

 {
 	"status": "[open/closed]",
 	"port": "[portValue]",
 	"remainingtime": "Mon DD, YYYY HH:MM:SS"
 }

Open SSH Access

Request:

 POST https://serveraddress/api/bssup/open

Params:

 {
 	"port": "[portValue]",	
 	"status": "open",
 	"timeout": [0/timeoutInSeconds]
 }

Response:

 {
 	"message": "",
 	"code": httpStatusCode
 }

Close SSH Access

Request:

 POST https://serveraddress/api/bssup/close

Response:

 {
 	"message": "message",
 	"code": httpStatusCode
 }

Get Active Sessions

Get active sessions

Request:

 GET https://serveraddress/api/bssup/sessions

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 https://serveraddress/api/bssup/{connId}/close

Response:

 {
 	"message": "message",
 	"code": httpStatusCode
 }

Get logs from database

Request:

 GET https://serveraddress/api/bssup/logs

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.

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.