Configure

Configure#

Restsh requires a configuration file for each host that should be accessed via REST.

The restsh.setup script can be used to create the initial configuration files.

restsh.setup add <type> <folder> <host>
    Type: One of f5, f5osa, gitlab, scm
    Folder: Subfolder in the config folder
    Host: Hostname of the REST endpoint

As an alternative you can copy one of the .restsh-config.dist files in the folder defined by the RESTSH_CONFIG_PATH environment variable (default is ${HOME}/.restsh-config). The filename must always start with .restsh-config-. All the configuration options are documented directly in this files.

To create a configuration file for your first F5 BIG-IP:

restsh.setup add f5 lab f5-lab-v17-1.lab.lan

To create a configuration file for your GitLab instance:

restsh.setup add gitlab lab gitlab.lab.lan

Pre-defined config files#

Prefix

Description

.restsh-config.dist.f5

F5 BIG-IP TMOS

.restsh-config.dist.f5osa

F5OS-A / rSeries

.restsh-config.dist.gitlab

GitLab

.restsh-config.dist.scm

Sectigo Cert Manager

Customize#

After initial creation of the configuration file you can adapt it to your needs. All configuration options are documented directly in the file.

Hint

The configuration files are simple shell scripts that are sourced by restsh.init.

Custom environment variables#

You can use the environment variable RESTSH_CUSTOM_ENV to define a custom file that will be sourced from restsh.init.

Enable modules#

Modules are enabled by setting the RESTSH_MODULES array.

RESTSH_MODULES=("aafw" "cert" "custom" "f5" "f5osa" "gitlab" "scm")

Certificate checking#

Restsh enables uses curl to communicate with the REST-APIs. Certificate checking is enabled in all default configurations. If you encounter certificate related errors you should add the signing certificate to your system trust store. Disabling certificate checking is NOT recommended, but you can set RESTSH_CURL_INSECURE=1 in the configuration file to disable it.

Proxy#

The easiest thing to do is not to use a proxy and allow direct connections. Restsh uses the system proxy settings (https_proxy and http_proxy environment variables) and supports basic authentication for the proxy. Simply set following variables in the configuration file:

RESTSH_CURL_PROXY_INSECURE="0"
RESTSH_CURL_PROXY_AUTH="basic"
RESTSH_CURL_PROXY_USER="<user>"
RESTSH_CURL_PROXY_PASS="<password>"

Securing passwords#

Sensitive values can be stored encrypted or in HashiCorp Vault, see Passwords and Secrets for details.

Enable debugging#

Print all executed commands and enables verbose mode of curl.

# Enable debug mode
export RESTSH_DEBUG=1

# Disable debug mode
unset RESTSH_DEBUG