Skip to content

Server configuration

Jump to bottom
Iaroslav Shepilov edited this page Mar 25, 2020 · 6 revisions

Script-server has default settings and works out of the box. For changing the settings, please edit conf/conf.json file (create new if needed).
You can set custom conf.json location by running Script server with -f parameter (e.g. launcher.py -f /home/me/configs/script-server.json)
Please note, that configuration changes require a server restart.

Example can be found at the bottom of the page.

Full list of configurable properties:

port

Listening port of the server.

Default: 5000 (5443 for ssl)
Type: number

address

Listening address of the server. Can be used to allow connections only from a specific network

Default: 0.0.0.0 (any connection)
Type: string (ip)

title

Custom web page title is shown to a user

Default: Script Server
Type: string

ssl

SSL configuration, use it for enabling communication over SSL
This would require an additional private key and certificate configuration (see below)

Default: ssl disabled
Type: json object

- key_path

The path to a private key file. Can be relative to script-server location or an absolute path

Required: yes
Type: string

- cert_path

The path to a public certificate file. Can be relative to script-server location or an absolute path

Required: yes
Type: string

auth

Enables user authentication. This configuration depends on the auth provider, specified by type property Auth providers require different settings

For detailed information on how authentication works and affects the script server, please read Authentication and Authorization

Type: json object

- type

Type of authentication provider. Supported types:

  • ldap (requires python ldap3 module)
  • google_oauth

For each provider description read corresponding sections on Authentication

Required: yes
Type: string

- url

(LDAP)
URL of the LDAP server

Required: yes
Type: string
Example: "url": "ldap://192.168.100.3",

- username_pattern

(LDAP)
Pattern for username, which is sent to the LDAP server, e.g. uid=$username,ou=people,dc=test,dc=ldap". $username is filled with the username, specified by user on login screen
This pattern can be useful, when user unique name in LDAP is more verbose than username.

Required: no
Default: "$username"
Type: string
Example1: "username_pattern": "uid=$username,ou=people,dc=buggy,dc=net"
Example2: "username_pattern": "[email protected]"
Example3: "username_pattern": "buggy\\$username"

- version

(LDAP)
LDAP protocol version. Supported versions:

  • 2
  • 3

Default: 3
Required: no
Type: number

- base_dn

(LDAP)
Base DN for resolving user attributes and groups. Required for getting user groups from LDAP.
base_dn should have format: "dc=name1,dc=name2,...dc=nameN"

base_dn can be resolved automatically from the following username_patterns:

Required: no
Default: resolved from username_pattern
Type: string
Example: "base_dn": "dc=buggy,dc=net"

- client_id

(Google OAuth)
Client ID, provided by Google

Required: yes
Type: string
Example: "client_id": "12345678.apps.googleusercontent.com"

- secret

(Google OAuth)
The secret, provided by Google
Environment variables can be used, prefixed by $$

Required: yes
Type: string
Example: "secret": "AbCdEfgHI"

access

Access configuration section can be used to completely prohibit access or to limit it. Allows configuring access groups and trusted users. Users should be specified either by:

  • their login name (if auth is enabled)
  • or IP (if auth is disabled and trusted_ips is enabled)

Any other names won't have an effect due to security reasons.
For detailed description , please see Authorization

Required: no
Type: json array

- allowed_users

List of allowed usernames, who can access the script-server. A single asterisk (*) stays for any user. By default, any user is allowed
Important note: users from groups and admin_users are always allowed. Thus there is no need to specify them explicitly.

Default: *
Required: no (yes for google_auth)
Type: json array (or * string)
Example1: "allowed_users": ["bob", "john", "[email protected]"]
Example2: "allowed_users": "*"]

- admin_users

List of users, who can access admin page (admin.html)

Default (without auth): ["127.0.0.1", "::1"]
Default (with auth): []
Required: no Type: json array

- full_history

List of users, who can see the execution history of other users
This should be a list of non-admin users (because admin_users can see full history anyway)

Default: []
Required: no
Type: json array

- groups

List of groups with the information, which users belong to each group. Users should be specified by username. There is an additional explicit group admin_users, which is created from the admin_users field. If this group is created explicitly, then admin_users property doesn't create its own group.
Groups can be references with @groupname syntax. Groups can even reference other groups

Type: json dict
Default: {}
Required: no
Example1:

{ "groups": {
	"dev": ["127.0.0.1"],
	"support": ["192.168.2.15", "192.168.2.15"]
}}

Example2:

{ "groups": {
	"dev": ["buggygm_gmail.com"],
	"all": ["@dev", "@admin_users"]
}}

- trusted_ips

This option allows specifying which IPs can be trusted. It has 2 effects:
On reverse proxies
All the requests, coming from reverse proxy has the same IP, so in audit information of the user, the IP of the proxy will be shown. To prevent it, you can put proxy's IP in the trusted_ips list, so the user IP will be resolved based on HTTP Headers from the proxy
On identification without auth
If auth is disabled, IP can be used to identify the users. But since IP is not very reliable, trusted IPs should be specified explicitly. If IP is not trusted, then each user would get a temporary identification token, which is harder to use in configuration (e.g. in admin_users or groups). More details can be found at Authorization

Type: json array
Default: []
Required: no
Example: "trusted_ips": ["192.168.0.15", "172.0.0.10"]

- user_header_name

(works only when auth is disabled)
Allows identifying users by an HTTP header. Can be used, when authentication is performed by a reverse proxy
See reverse-proxy-auth for details

Type: string
Required: no
Example: "user_header_name": "X-Forwarded-User"

alerts

Configuration section for alert notifications in case of script execution failure.
Notifications contain script name, username, exit code, and an attached log file.

Type: json object
Required: no

- destinations

List of destinations, where an alert should be sent to. Multiple destinations can be configured at once, even for the same type.

Type: json array Default: []

--- type

Type of destination. Supported values:
email
requires smtplib module
Alert is sent as an email. The execution log file will be attached as a file

http
requires requests module
The alert message is sent to an HTTP server via POST request. The alert message will be sent in the request body, under message name.
The execution log file will be attached as a multipart file with "log" name.

Type: string
Required: yes

--- from

(email)
Sender email address.

Required: yes
Type: string

--- to

(email)
Semicolon-separated list of recipients' email addresses

Required: yes
Type: string

--- server

(email)
Server hostname/IP, which is used to send an email

Required: yes
Type: string

--- auth_enabled

(email)
A boolean flag specifying if authentication is required to send an email.

Default: false (true, if login or password are set)
Required: no
Type: boolean

--- login

(email)
Username for authentication in the server

Default: from field
Required: no
Type: string

--- password

(email) Password for authentication in the server
Environment variables can be used, prefixed by $$

Required: no
Default: -
Type: string
Example1: "password": "$$EMAIL_PWD"

--- tls

(email) Specifies, whether the server requires TLS layer

Default: false (true for gmail server)
Required: no
Type: boolean

--- url

(http) A URL where the alert notification will be sent to.

Required: yes
Type: string
Example: "url": "localhost:5000/test_alerts"

logging

Section for logging configuration

Type: json dict
Required: no

- execution_file

Filename pattern for script execution logs.
Each execution is always written to a separate file, so if the filename is not unique, it's prefixed with a random value.
The following variables can be used (via $varname or ${varname} syntax):

  • ID - execution identificator
  • USERNAME - authentication name of the user
  • IP - IP of the user
  • HOSTNAME - hostname of the user
  • DATE - current date and time (in execution_date_format format)
  • AUDIT_NAME - audit name of the user
  • SCRIPT - script name
    .log suffix is not required and can added automatically

Default: "${SCRIPT}${AUDIT_NAME}${DATE}.log"
Required: no
Type: string
Example1: "execution_file": "$ID.log"
Example2: "execution_file": "${IP}-${SCRIPT}"

- execution_date_format

Date format to be used for execution_file.
Should be a python format: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior

Default: "%y%m%d_%H%M%S" Required: no Type: string Example: "execution_date_format": "%y-%m-%d_%H-%M-%S"

Example

{
  "port": 8080,
  "address": "192.168.0.1",
  "title": "My Script Server"
  "ssl": {
    "key_path": "testing/ssl/script-server.key",
    "cert_path": "testing/ssl/script-server.crt"
  },
  "auth": {
    "type": "ldap",
    "url": "ldap://127.0.0.1",
    "username_pattern": "uid=$username,ou=people,dc=test,dc=ldap",
    "version": 3,
    "base_dn": "dc=test,dc=ldap",
    "client_id": "12345678.apps.googleusercontent.com",
    "secret": "AbCdEfgHI"
  },
  "access": {
	"allowed_users": [ "myname", "my_friend", "jack", "joe", "jihn" ],
	"admin_users": [ "[email protected]", "myname" ],
	"groups": {
		"dev": ["jack", "joe", "jihn"],
		"support": ["my_friend"],
		"all": ["@admin_users", "@dev", "@support", "alice"]
	},
	"trusted_ips": [ "192.168.0.1", "192.168.0.2" ]
  },
  "alerts": {
    "destinations": [
      {
        "type": "email",
        "from": "[email protected]",
        "to": "[email protected]",
        "server": "smtp.gmail.com",
        "auth_enabled": true,
        "login": "[email protected]",
        "password": "$$EMAIL_PWD",
        "tls": true,
        "url": "localhost:5000/test_alerts"
      }
    ]
  },
  "logging": {
    "execution_file": "$DATE-$ID.log",
    "execution_date_format": "%y-%m-%d_%H-%M"
  }
}
Clone this wiki locally