Skip to content

Server configuration

Jump to bottom
Iaroslav Shepilov edited this page Oct 15, 2023 · 20 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).
It's recommended not to take an example configuration as it is, as it contains a lot values, which you don't need most probably. Only enable those options, which are really needed for you (for example, authentication).

Example can be found at the bottom of the page.

Additionally, Script server supports the following command-line arguments:

  • -f, --config-file - filename, where server configuration is read from. Can be absolute path to a file (default: conf.json)
  • -d, --config-dir - directory, where configuration file is stored (default: script-server/conf)
  • -l, --log-folder - where log files will be stored to (default: script-server/log)
  • -t, --tmp-folder - where temp files will be stored to (default: script-server/temp)

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

max_request_size

Allows specifying max accepted file size (in megabytes) for upload.
Use this parameter if your users upload huge files, or, to the contrary, when you want to allow uploading only small files (not to occupy the server storage)

Default: 10
Type: number

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
  • gitlab
  • htpasswd

For each provider description read corresponding sections on Authentication

Required: yes
Type: string

- expiration_days

Number of days to keep a user authenticated after his initial login.
The property can be a real number, e.g. 0,5.

Required: no
Type: float
Default: 30

- url

(LDAP, Gitlab)
URL of the LDAP/Gitlab server
For LDAP it can also be an array of multiple LDAP servers. In this case, the pooling method will be Round Robin

Required: yes (for LDAP), no (for Gitlab) Type: string
Example: "url": "ldap://192.168.100.3",
Example: "url": ["ldap://192.168.100.3", "ldap://192.168.100.4"],
Default: https://gitlab.com (for Gitlab)

- 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": "$username@buggy.net"
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, Gitlab)
Client ID in OAuth provider

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

- secret

(Google OAuth, Gitlab)
The secret in OAuth provider Environment variables can be used, prefixed by $$

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

- group_support

(Gitlab)
Enabled loading user groups from Gitlab. This requires Gitlab 'api' scope

Required: no
Type: boolean
Default: true

- group_search

(Gitlab)
Optional filter for user groups, if there are too many groups for users

Required: no
Type: boolean
Example: "group_search": "developers/"

- auth_info_ttl

(Google OAuth, Gitlab)
Time (in milliseconds) to cache user and group information before requested it from Gitlab server again, default 0 - cache forever and never check Gitlab again

Required: no
Type: integer
Default: 0

- session_expire_minutes

(Google OAuth, Gitlab)
User session expiration time. If a user stays inactive for more than the expiration time, he is logged out and has to authenticate again. By default, there is only server-wide expiration of 30 days.

Required: no
Type: integer
Default: 0 (no expiration)

- state_dump_file

(Google OAuth, Gitlab)
File path where to persist user/group information, default - only memory used (restarting app will logout all users).

Required: no
Type: string

- htpasswd_path

(.htpasswd)
File path with stored .htpasswd credentials

Required: yes (for .htpasswd auth) Type: string

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", "me@domain.com"]
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

- code_editors

(v 1.17)
List of admin users, who can edit/upload scripts code ticket #284. Please note, that these users would be able to view and modify any file on server (if OS user has access to it).
By default, all admins can edit script code.

Default: ['@admin_users']
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
In trusted_ips you can specify either an IP address or IP subnet (see the syntax in the example below). Subnets might be helpful for docker or dynamic addresses.

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

- 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
    (v 1.18) Since this version you can also use parameter values as a template variable. Important!: you should use ${parameter name} syntax, i.e. always with curly braces.

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"

secret_storage_file

Allows to specify a location for secret.dat file, which is used cookie encryption. This option is helpful for docker containers, when recreating the container destroys the generated file and all the users have to log in again

Default: temp folder of script-server
Required: no _Type: string

security

Section for security configuration.
Script server comes with the most strict security configuration, so it's recommended not to touch this section unless really needed.

Type: json dict
Required: no

- xsrf_protection

Allows configuring the level of XSRF protection.
Options:

  • token (default): users are protected via a unique XSRF token. This is the most secure and recommended option
  • header: Script server requires X-Requested-With header (any value) to be send with any PUT/POST request. This protection relies on CORS protection, i.e. that attacker site cannot call AJAX to another domain. In most of the cases CORS protection is reliable, and can only be bypassed in very special circumstances. Thus header XSRF protection is just slightly less protected than token
  • disabled: no XSRF protection will be done

Type: string
Required: no
Default: token

script_groups

(v 1.19)
Allows to configure script groups.

Type: json dict
Required: no

- group_by_folders

(v 1.19)
Makes scripts to be groupped automatically (see script group) according to sub-directories inside runners folder.

Type: boolean
Required: no
Default: true

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": [ "buggy@gmail.com", "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": "buggygm@gmail.com",
        "to": "buggygm@gmail.com",
        "server": "smtp.gmail.com",
        "auth_enabled": true,
        "login": "buggygm@gmail.com",
        "password": "$$EMAIL_PWD",
        "tls": true,
        "url": "localhost:5000/test_alerts"
      }
    ]
  },
  "logging": {
    "execution_file": "$DATE-$ID.log",
    "execution_date_format": "%y-%m-%d_%H-%M"
  },
  "security": {
    "xsrf_protection": "token"
  }
}
Clone this wiki locally