The Configuration File

Exosphere loads all of its settings and inventory from a configuration file. The configuration file can be provided in multiple formats, including yaml, toml, and json.

Location

Where the configuration file lives will depend on your platform. For instance, for a YAML configuration file, the default locations are:

Linux, Unix

~/.config/exosphere/config.yaml

macOS

~/Library/Application Support/exosphere/config.yaml

Windows

%LOCALAPPDATA%\exosphere\config.yaml

You can of course substitute the file extension with .toml or .json if you wish to use those formats instead.

You can also ask Exosphere where it expects the configuration file to be on your platform:

exosphere config paths

Additionally, you can specify a custom configuration file location via the EXOSPHERE_CONFIG_FILE environment variable, with the full path to the file as the value.

Structure

Below is a full example of a configuration file, in all supported formats. Any option left out will use the default values, which are documented below.

YAML

options:
  log_level: DEBUG
  max_threads: 5  # Limit parallel actions to 5 threads
  default_username: alice  # Default username across hosts (optional)
hosts:
  - name: host1
    ip: host1.example.com
  - name: host2
    ip: host2.example.com
    port: 2222
    description: "Example Host"
  - name: host3
    ip: host3.example.com
    description: "Another Example Host"
    username: admin  # Override username for this host
    sudo_policy: nopasswd

TOML

[options]
log_level = "DEBUG"
max_threads = 5 # Limit parallel actions to 5 threads
default_username = "alice" # Default username across hosts (optional)

[[hosts]]
name = "host1"
ip = "host1.example.com"

[[hosts]]
name = "host2"
ip = "host2.example.com"
port = 2222
description = "Example Host"

[[hosts]]
name = "host3"
ip = "host3.example.com"
description = "Another Example Host"
username = "admin" # Override username for this host
sudo_policy = "nopasswd"

JSON

{
    "options": {
        "log_level": "DEBUG",
        "max_threads": 5,
        "default_username": "alice"
    },
    "hosts": [
        {
            "name": "host1",
            "ip": "host1.example.com",
            "description": "Example Host"
        },
        {
            "name": "host2",
            "ip": "host2.example.com",
            "port": 2222,
            "description": "Example Host"
        },
        {
            "name": "host3",
            "ip": "host3.example.com",
            "description": "Another Example Host",
            "username": "admin",
            "sudo_policy": "nopasswd"
        }
    ]
}

The configuration file is split into two main sections, Options and Hosts. The Options section contains general settings for Exosphere, while the Hosts section contains the Inventory of hosts that Exosphere will connect to.

Environment Variables

The location of the configuration file can be overridden by setting the EXOSPHERE_CONFIG_FILE environment variable to the full path of the file you wish to use.

Unix/macOS

export EXOSPHERE_CONFIG_FILE="/path/to/my/config.yaml"

Windows/PowerShell

$env:EXOSPHERE_CONFIG_FILE = "c:\path\to\my\config.yaml"

Windows/cmd

set EXOSPHERE_CONFIG_FILE="c:\path\to\my\config.yaml"

Tip

There is also EXOSPHERE_CONFIG_PATH, which you can use to specify a directory where a config file named config.{yaml,yml,toml,json} will be searched for. This can be useful in certain deployments.

Exosphere also supports loading configuration options from environment variables. You can use this to override any specific Option from the configuration file. You cannot use environment variables to override the Hosts section.

The environment variable names are prefixed with EXOSPHERE_OPTIONS_ and the option name in uppercase.

For example, to override the log_level option, set the following environment variable:

Unix/macOS

export EXOSPHERE_OPTIONS_LOG_LEVEL="DEBUG"

Windows/PowerShell

$env:EXOSPHERE_OPTIONS_LOG_LEVEL = "DEBUG"

Windows/cmd

set EXOSPHERE_OPTIONS_LOG_LEVEL=DEBUG

This pattern applies to all configuration options.

Note

Option types are all strings in this context, but they will be parsed as json types when loaded. This means "true" and "false" will correctly be interpreted as booleans, and "null" will be interpreted as None. Essentially, you do not need to worry about it as type conversion is properly handled automatically.

Exosphere can display which environment variables are influencing the configuration (if any):

exosphere config source

Options

The options section contains general settings for Exosphere. These options are applied globally, and affect how Exosphere behaves at runtime.

Below is a detailed list of all available options, their defaults, and examples of how to set them in the configuration file.

log_level

The logging level for Exosphere. This can be set to one of the following values, as a string:

DEBUG
INFO
WARNING
ERROR

This controls the verbosity of the logs generated by Exosphere.

Default: INFO

Example:

YAML

options:
  log_level: DEBUG

TOML

[options]
log_level = "DEBUG"

JSON

{
    "options": {
        "log_level": "DEBUG"
    }
}

default_sudo_policy

The global sudo policy to use when running commands on hosts. This can be set to one of the following values:

skip: Do not run commands that require sudo at all
nopasswd: Assume sudoers configuration allows running the provider commands without a password

This controls how Exosphere will handle sudo permissions when running commands on hosts. The default is skip, which means Exosphere will not attempt to use sudo at all.

If you want Exosphere to run commands that require elevated privileges at all, you must configure your sudoers file to allow the user Exosphere connects as to run those commands with NOPASSWD: in the sudoers file.

More details on how to configure this can be found in the Sudo Policies and Privileges documentation.

Note

Depending on the Providers you use, you may not need to configure this at all! See the Providers documentation for more details.

This is the global value that, by default, applies to all hosts. It can be overridden on a per-host basis in the inventory, inside the hosts section, via sudo_policy.

Default: skip

Example:

YAML

options:
  default_sudo_policy: nopasswd

TOML

[options]
default_sudo_policy = "nopasswd"

JSON

{
    "options": {
        "default_sudo_policy": "nopasswd"
    }
}

debug

Enable debug mode, which sets the root logger to DEBUG level. This is useful for development and debugging purposes, if you also want to see debug logs from libraries and other components.

Normally, there's very little reason to enable this unless you are actively developing Exosphere or troubleshooting a specific issue.

Caution

Enabling debug mode will absolutely flood your logs with debug messages from both Exosphere and all of its dependencies. We do not recommend enabling this unless you know what you are doing.

You probably want to set log_level to DEBUG instead.

Default: false

Example:

YAML

options:
  debug: true

TOML

[options]
debug = true

JSON

{
    "options": {
        "debug": true
    }
}

log_file

A filesystem path to a file where Exosphere will write logs. If not set, Exosphere will use the platform default location for application logs.

You can set this to any valid path on your filesystem where you have write permissions.

Default: (Platform Default)

Example:

YAML

options:
  log_file: /home/alice/tmp/exosphere.log

TOML

[options]
log_file = "/home/alice/exosphere.log"

JSON

{
    "options": {
        "log_file": "/home/alice/exosphere.log"
    }
}

log_max_bytes

The maximum size, in bytes, that the log_file may reach before it is rotated. When the log file grows past this size, it is rolled over and a fresh file is started.

This only applies when logging to a file; it has no effect on console logging. Set to 0 to disable rotation entirely and let the log grow without bound.

Default: 5242880 (5 MiB)

Example:

YAML

options:
  log_max_bytes: 10485760  # 10 MiB

TOML

[options]
log_max_bytes = 10485760  # 10 MiB

JSON

{
    "options": {
        "log_max_bytes": 10485760
    }
}

log_backup_count

The number of rotated log files to keep. When log_file is rotated, older files are named with a numeric suffix (e.g. exosphere.log.1), and any beyond this count are deleted.

With the defaults, the total disk used by logs is therefore essentially log_max_bytes * (log_backup_count + 1).

This must be a positive integer of 1 or more, any lower value is rejected as invalid.

To disable rotation entirely, set log_max_bytes to 0 instead.

Default: 3

Example:

YAML

options:
  log_backup_count: 5

TOML

[options]
log_backup_count = 5

JSON

{
    "options": {
        "log_backup_count": 5
    }
}

history_file

A filesystem path to a file where Exosphere will store the REPL history. If not set, Exosphere will use the platform default and name the file repl_history.

This file is used to persist the command history across executions of Exosphere, allowing you to navigate through or search for previously executed commands.

Default: (Platform Default)

Example:

YAML

options:
  history_file: /home/alice/.exosphere_history

TOML

[options]
history_file = "/home/alice/.exosphere_history"

JSON

{
    "options": {
        "history_file": "/home/alice/.exosphere_history"
    }
}

history_max_entries

The maximum number of entries to retain in the history_file. The history file is trimmed to the most recent entries when the interactive REPL starts, so it cannot grow without bound.

Set to 0 to disable trimming and keep unlimited history.

Default: 1000

Example:

YAML

options:
  history_max_entries: 5000

TOML

[options]
history_max_entries = 5000

JSON

{
    "options": {
        "history_max_entries": 5000
    }
}

cache_autosave

Automatically save the state to disk when changes are made. This is on by default, and probably should not be turned off unless you have a very specific reason to do so.

If this is disabled, you will need to manually save the state with inventory save from the interactive mode for changes to systems state to persist across executions.

See Managing Cache for more details on the cache file

Caution

Note that a manual save can only be done in interactive mode. Running Exosphere in non-interactive mode with this option disabled will not save the state at all between executions.

Default: true

Example:

YAML

options:
  cache_autosave: false

TOML

[options]
cache_autosave = false

JSON

{
    "options": {
        "cache_autosave": false
    }
}

cache_autopurge

Whether or not to automatically remove hosts from cache when they are removed from the configuration file.

If cache_autosave is set to False, this option has no effect.

Note

If all of the hosts are removed from the configuration file, Exosphere will err on the side of caution and leave the cache file alone, regardless of this setting.

This is to prevent accidental cache loss if the wrong configuration is loaded, or if the file is made temporarily inaccessible.

If you really want to remove all the contents of the cache file, use the exosphere inventory clear command.

Default: true

Example:

YAML

options:
  cache_autopurge: false

TOML

[options]
cache_autopurge = false

JSON

{
    "options": {
        "cache_autopurge": false
    }
}

cache_file

A filesystem path to a file where Exosphere will store the state of the inventory. If not set, Exosphere will use the platform default location for the cache file.

This file is used to persist the state of the inventory across executions, including the results of discovery, host updates, last check times, and more.

The file is lzma compressed to save space, and is not human readable.

It can be cleared with the exosphere inventory clear command, without having to delete the file manually.

See Managing Cache for more details on the cache file

Default: (Platform Default)

Example:

YAML

options:
  cache_file: /home/alice/tmp/exosphere.db

TOML

[options]
cache_file = "/home/alice/tmp/exosphere.db"

JSON

{
    "options": {
        "cache_file": "/home/alice/tmp/exosphere.db"
    }
}

stale_threshold

The number of seconds after which a host's data is considered stale.

If a host has not been refreshed in this many seconds, an asterisk or similar flag will be shown in the UIs to indicate that the update count may not be accurate, and that the host should be refreshed.

The default is 24 hours, which is reasonable, but you may want a shorter or longer span of time depending on your environment.

Default: 86400 (24 hours)

Example:

YAML

options:
  stale_threshold: 3600  # 1 hour

TOML

[options]
stale_threshold = 3600  # 1 hour

JSON

{
    "options": {
        "stale_threshold": 3600
    }
}

default_timeout

The number of seconds to wait for a response from a host over SSH.

This is the maximum time Exosphere will wait for a response from a host before timing out, flagging the host as offline, or raising an error condition.

This is useful for hosts that may be slow to respond, or if you have a large number of hosts and want to avoid long delays on That One Host.

Note

This is the global value that, by default, applies to all hosts. It can be overridden on a per-host basis in the inventory, inside the hosts section, via connect_timeout.

Default: 10 (seconds)

Example:

YAML

options:
  default_timeout: 60  # 1 minute

TOML

[options]
default_timeout = 60  # 1 minute

JSON

{
    "options": {
        "default_timeout": 60
    }
}

default_username

The default SSH username to use when connecting to hosts. This is useful if you have a common username across all hosts, and do not want to specify it for each host in the inventory.

If not set, Exosphere will try to use the current user's username on the system where Exosphere is running.

Note

This is the global value that, by default, applies to all hosts. It can be overridden on a per-host basis in the inventory, inside the hosts section, via username.

Default: None (Current user's username)

Example:

YAML

options:
  default_username: alice  # Use 'alice' as the default SSH username

TOML

[options]
default_username = "alice"  # Use 'alice' as the default SSH username

JSON

{
    "options": {
        "default_username": "alice"
    }
}

default_ssh_locale

The locale forced on every command Exosphere runs on a remote host.

Some exosphere providers have to rely on parsing the human-readable output of remote commands to determine the state of the host.

Since many of these commands are subject to gettext translation, which changes on the remote host depending on the locale, this can lead to non-deterministic results.

In order to prevent this scenario, Exosphere, by default, forces the locale on the remote host to C (POSIX locale), which is guaranteed to be available and will always produce canonical, untranslated output.

A reasonable alternative, if available, is C.UTF-8.

Attention

Unless you have a very specific reason to do so, we do not recommend changing this value from the default, as it may break functionality in some providers.

Default: C

Example:

YAML

options:
  default_ssh_locale: C.UTF-8

TOML

[options]
default_ssh_locale = "C.UTF-8"

JSON

{
    "options": {
        "default_ssh_locale": "C.UTF-8"
    }
}

max_threads

The maximum number of threads to use for parallel operations.

This is the maximum number of threads Exosphere will use for parallel operations, such as discovery, ping, checking for updates or synchronizing repositories.

This can be useful to limit the number of concurrent operations, especially in environments with many hosts, to avoid overwhelming the network or the computer where you are running Exosphere.

The default is a generous 15 threads, which you may want to lower depending on your context.

Default: 15

Example:

YAML

options:
  max_threads: 5  # Limit parallel actions to 5 threads

TOML

[options]
max_threads = 5  # Limit parallel actions to 5 threads

JSON

{
    "options": {
        "max_threads": 5
    }
}

ssh_pipelining

Enable SSH connection pipelining to improve performance when connecting to multiple hosts.

By default, Exosphere closes connections automatically after each Host operation (sync, discover, refresh, ping etc).

Enabling this option will leave connections open for reuse across multiple operations, significantly improving performance in workflows that involve multiple operations on the same hosts.

Idle connections will be closed automatically after a certain period of time, configurable via ssh_pipelining_lifetime, and reaped periodically via ssh_pipelining_reap_interval.

Default: false

Example:

YAML

options:
  ssh_pipelining: true

TOML

[options]
ssh_pipelining = true

JSON

{
    "options": {
        "ssh_pipelining": true
    }
}

ssh_pipelining_lifetime

The number of seconds an idle SSH connection will be kept open when SSH pipelining is enabled.

This setting only applies if ssh_pipelining is set to true.

When a connection has been idle (unused) for longer than this duration, it will be closed by the connection reaper thread.

Attention

Setting this value too low may negate the performance benefits of SSH pipelining, as connections will be closed before they can be reused.

You will get a warning in the logs to this effect if you configure this value to be less than 60 seconds. Consider setting this to at least the longest time an operation may take on your slowest host, as a baseline.

Otherwise, you can leave this at the default value.

Default: 300 (5 minutes)

Example:

YAML

options:
  ssh_pipelining_lifetime: 240  # 4 minutes

TOML

[options]
ssh_pipelining_lifetime = 240  # 4 minutes

JSON

{
    "options": {
        "ssh_pipelining_lifetime": 240
    }
}

ssh_pipelining_reap_interval

The interval (in seconds) at which the reaper thread wakes up to check for and close idle SSH connections when SSH pipelining is enabled.

This setting only applies if ssh_pipelining is set to true.

Attention

Setting this value too high will cause idle connections to remain open for longer than necessary, potentially extending their lifetime beyond ssh_pipelining_lifetime by up to this interval duration.

Conversely, having the reaper thread wake up frequently has negligible overhead since it will only perform work when there are actually idle connections to close.

You should consider that this value effectively adds up to this amount of time to the actual lifetime of idle connections. For example, with a lifetime of 300s and an interval of 30s, connections may remain open for up to 330s.

If in doubt, leave this at the default value.

Default: 30 (30 seconds)

Example:

YAML

options:
  ssh_pipelining_reap_interval: 60  # 1 minute

TOML

[options]
ssh_pipelining_reap_interval = 60  # 1 minute

JSON

{
    "options": {
        "ssh_pipelining_reap_interval": 60
    }
}

update_checks

Whether or not Exosphere is allowed to check for updates on PyPI.

Exosphere currently doesn't perform any automatic update checks, only when explicitly asked to via the version check command.

This option allows you to disable that functionality entirely.

This is intended for:

Environments that have stringent policies about external connectivity
Environments where Exosphere is installed by other means than PyPI
Brave souls who would package Exosphere in the context of an OS distribution.

In all of these contexts, the version check command will be disabled and print a clear message instead.

If in doubt, leave this at the default value.

Default: true

Example:

YAML

options:
  update_checks: false

TOML

[options]
update_checks = false

JSON

{
    "options": {
        "update_checks": false
    }
}

no_banner

Do not show the ascii banner when starting Exosphere in interactive mode. Setting this to true will suppress the banner entirely, showing only the welcome text and the prompt.

Tip

This can be set contextually with the environment variable EXOSPHERE_OPTIONS_NO_BANNER set to true. For more details see Environment Variables.

Default: false

Example:

YAML

options:
  no_banner: true

TOML

[options]
no_banner = true

JSON

{
    "options": {
        "no_banner": true
    }
}

editor

The editor command used by the config edit command to open the configuration file.

When unset, Exosphere falls back to the VISUAL environment variable, then EDITOR, and finally a platform default (notepad on Windows, vi everywhere else).

The value is a command that may include arguments.

Attention

For graphical editors that return immediately, pass the appropriate "wait" or "block" flag so Exosphere can validate the file once you are done editing (for example: code --wait, subl -w, or gvim -f).

On Windows, a path that contains spaces must be quoted within the value, or it will be ambiguous and fail to resolve. See the examples below for the correct form in each format. A bare command found on PATH (like code --wait) needs no quoting.

Tip

This can be set contextually with the environment variable EXOSPHERE_OPTIONS_EDITOR. For more details see Environment Variables.

Default: (Unset) (use VISUAL / EDITOR / platform default)

Example:

YAML

Command on path

options:
  editor: "code --wait"

Windows path with spaces and arguments

options:
  editor: '"C:\Program Files\Editor\ed.exe" --wait'

TOML

Command on path

[options]
editor = "code --wait"

Windows path with spaces and arguments

[options]
editor = '"C:\Program Files\Editor\ed.exe" --wait'

JSON

Command on path

{
    "options": {
        "editor": "code --wait"
    }
}

Windows path with spaces and arguments

{
    "options": {
        "editor": "\"C:\\Program Files\\Editor\\ed.exe\" --wait"
    }
}

Inventory

The second section of the configuration file is the Hosts section, which is referred to throughout the documentation as The Inventory.

The Hosts section contains a list of hosts that Exosphere will connect to, as well as their connection parameters and any specific option for each host.

Host entries are structured as follows. This example describes two hosts, one of which has a custom connection timeout value set, overriding default_timeout.

YAML

hosts:
  - name: myhost
    ip: myhost.example.com
  - name: anotherhost
    ip: 127.0.1.8
    connect_timeout: 30

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"

[[hosts]]
name = "anotherhost"
ip = "127.0.1.8"
connect_timeout = 30

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com"
        },
        {
            "name": "anotherhost",
            "ip": "127.0.1.8",
            "connect_timeout": 30
        }
    ]
}

Mandatory fields for each host entry are:

name: The name of the host, which is used to identify it in the UI and logs.
ip: The address of the host, which can be a hostname or an IP address.

Optional fields for each host entry include:

port: The SSH port to connect to the host. Defaults to 22.
username: An optional SSH username to use when connecting to the host
description: A short string describing the host, to be displayed in UIs
connect_timeout: The number of seconds to wait for a response from the host over SSH
sudo_policy: The sudo policy to use when running commands on the host
ssh_locale: The locale forced on remote commands run against the host

Below is the detailed list of all available host options and their defaults.

name

The name of the host, which uniquely identifies the host within the inventory. It is recommended to keep this to a short string rather than a fully qualified domain name, although it can be arbitrary.

Attention

The name field has a unicity constraint within the inventory! You cannot have two hosts with the same name value, and Exosphere will inform you of this if it is the case, before promptly refusing to load the configuration file.

Mandatory: Yes

Example:

YAML

hosts:
  - name: myhost

TOML

[[hosts]]
name = "myhost"

JSON

{
    "hosts": [
        {
            "name": "myhost"
        }
    ]
}

ip

The IP address or hostname of the host to connect to over SSH. This can be a fully qualified domain name, an IP address, or a short hostname, so long as it resolves. It is recommended to use a fully qualified domain name or an IP address to avoid issues with DNS resolution.

Attention

The ip field must not contain the @ character. To specify a username, use the username field instead.

Mandatory: Yes

Example:

YAML

hosts:
  - name: myhost
    ip: myhost.example.com

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com"
        }
    ]
}

port

The SSH port to connect to the host. This is optional, and defaults to 22. If your host uses a different port for SSH, you can specify it here.

Default: 22

Example:

YAML

hosts:
  - name: myhost
    ip: myhost.example.com
    port: 2222

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
port = 2222

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com",
            "port": 2222
        }
    ]
}

username

An optional SSH username to use when connecting to the host.

Note

This option has precedence over default_username

This is useful if you need to connect to a particular host with a different user than the one you are running Exosphere as, or the one configured globally in default_username.

Default: Current user's username

Example:

YAML

hosts:
  - name: myhost
    ip: myhost.example.com
    username: alice

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
username = "alice"

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com",
            "username": "alice"
        }
    ]
}

description

A short string describing the host, to be displayed in UIs. This is optional, but can be useful to provide additional context about the host, such as its role or purpose.

Default: None

Example:

YAML

hosts:
  - name: myhost
    ip: myhost.example.com
    description: "Web Server"

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
description = "Web Server"

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com",
            "description": "Web Server"
        }
    ]
}

connect_timeout

The number of seconds to wait for a response from the host over SSH. This is optional, and defaults to the value set in default_timeout.

If you have hosts that are particularly slow to respond, you can increase this value on a per-host basis.

Default: Value of default_timeout

Example:

YAML

hosts:
  - name: myhost
    ip: myhost.example.com
    connect_timeout: 30  # 30 seconds

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
connect_timeout = 30  # 30 seconds

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com",
            "connect_timeout": 30
        }
    ]
}

sudo_policy

The sudo policy to use when running commands on the host.

Note

This option has precedence over the global option, see default_sudo_policy for documentation and usage details.

Default: Value of default_sudo_policy

Example:

YAML

hosts:
  - name: myhost
    ip: myhost.example.com
    sudo_policy: nopasswd

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
sudo_policy = "nopasswd"

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com",
            "sudo_policy": "nopasswd"
        }
    ]
}

ssh_locale

The locale forced on remote commands run against this host.

Note

This option has precedence over the global option, see default_ssh_locale for documentation and usage detail.

Attention

Unless you have a very specific reason to do so, we do not recommend changing this value from the default, as it may break functionality in some providers.

Default: Value of default_ssh_locale

Example:

YAML

hosts:
  - name: myhost
    ip: myhost.example.com
    ssh_locale: C.UTF-8

TOML

[[hosts]]
name = "myhost"
ip = "myhost.example.com"
ssh_locale = "C.UTF-8"

JSON

{
    "hosts": [
        {
            "name": "myhost",
            "ip": "myhost.example.com",
            "ssh_locale": "C.UTF-8"
        }
    ]
}