Configuring fotoobo

Introduction

fotoobo.yaml

fotoobo reads its configuration from a global configuration file, usually named fotoobo.yaml. If you do not explicitly set a file (with the command line option -c ) fotoobo searches at the following locations for a file named fotoobo.yaml (in the order given here):

In the current working directory
In $HOME/.config/

It will take the first file given and stop searching for other files.

If you do not specify a configuration file and fotoobo does not find it in the local directory it runs with default settings which are referenced below.

The file fotoobo.yaml.sample provides a skeleton of a fotoobo.yaml configuration with all possible options and the respective documentation for it. Use this as a starting point for your own configuration.

CLI-Options

Always keep in mind that the cli options take precedence over the global configuration options. So, even if there is a global configuration file you may override some of the settings in it with cli options.

The following list of options are in alphabetical order. In the configuration file the order of the options does not matter, even if there are dependencies between them.

Note that you can have many basic settings changed by CLI-options, but some more advanced things like audit logging to a syslog server can only be achieved by using file based configuration.

Settings Reference

General Settings

inventory

default: “inventory.yaml”

The path and/or filename of the The fotoobo inventory. If fotoobo needs to connect to a Fortinet device it loads the needed configuration from this inventory. If you omit the path fotoobo will search in the current working directory.

no_logo

default: false

Suppress the output of the fotoobo logo at the beginning of the execution. Set this value to True to suppress the logo.

Logging

NOTE: The settings here apply the same to normal logging and audit logging.

If you configure a logging setting it is automatically enabled. Otherwise default logging will be used. Default logging is set to log to console with log-level WARNING.

level

default: “WARNING”

Choose one of the following log levels for logging: CRITICAL, ERROR, WARNING, INFO, DEBUG. This option is not case sensitive, so it also works if you set it to warning instead of WARNING.

log_console

default: enabled

Whether fotoobo should print all logs to console or not. Defaults to yes. To disable console logging comment out this line using a #.

log_file

default: enabled

The sup-option name holds the path and/or filename where fotoobo writes the logfile to. If you set a log file the logs are appended to a file if the file already exists. If you omit the path the current working directory is used.

If you want to disable file logging, comment the respective lines out using a #.

log_syslog

default: disabled (commented out)

The configuration to log to syslog. If you need this, remove the comment values (#) and set the values of host, port and protocol to the correct values.

log_configuration_file

default: disabled (commented out)

If you want to fine tune logging even more, you can provide an own python logging configuration file. There is a logging.config.sample where you can find more information about this. Uncomment the line and point it to your logging.config file to have the custom logging configuration take effect.

NOTE:

If this settings is set, all the above will be ignored.
If this settings is set, the audit logging too must be configured in the custom logging config. Mixing logging configurations from fotoobo.yaml and a custom logging.config is not supported.

Audit-Logging

fotoobo can produce audit log trails (usually this is just which user called what fotoobo command line from which host when).

The configuration options work the same as described in Logging.

NOTE:

If log_configuration_file is set, the settings of this part has no effect and you MUST configure audit logging in the log_configuration_file too.

Hashicorp Vault Service

For security reasons it may not be safe enough to store sensitive data like credentials and tokens directly in the fotoobo inventory file. Instead the Hashicorp Vault service may be used to store such data. In the fotoobo inventory file you may use VAULT as a placeholder for any attribute.

The Vault client in fotoobo will use the approle login to get the data.

The data stored in the Vault service has to be a dictionary which reflects the structure of the fotoobo inventory and its attributes. fotoobo will replace all attributes that have the value VAULT with the value stored in the vault dictionary.

Example

An example inventory file

fortigate-demo:
  hostname: fortigate.local
  token: VAULT
  type: fortigate

fortimanager-demo:
  hostname: fortimanager.local
  username: demo
  password: VAULT
  type: fortimanager

Data structure in the Vault servcie

{
  "fortigate-demo": {
    "token": "your-secret-token"
  },
  "fortimanager-demo": {
    "password": "your-secret-password"
  }
}

The following configuration options are to be set under a settings group called vault. If you omit the whole vault section, the use of the Hashicorp Vault service is disabled (default).

url

The Hashicorp Vault Service URL in the form https://vault.local

namespace

The Namespace to access

data_path

The path in the Vault service where the sensitive data is stored. The data has to be a dictionary which reflects the structure of the fotoobo inventory and its attributes.

role_id

The approle role_id

Instead of storing the role_id in the yaml configuration file you may use the system environment variable FOTOOBO_VAULT_ROLE_ID to store that value. The environment variable takes precedence over the configuration file should both be defined.

secret_id

The approle secret_id

Instead of storing the secret_id in the yaml configuration file you may use the system environment variable FOTOOBO_VAULT_SECRET_ID to store that value. The environment variable takes precedence over the configuration file should both be defined.

ssl_verify (optional, default: True)

Check host SSL certificate (true) or not (false). You can also provide a path to a custom CA certificate or CA bundle. Please be aware that disabling SSL certificate verification is a security risk and should not be used in a production environment.

token_file (optional)

The file to cache the vault token. If you omit this cache file the Vault client will always relogin with role_id and secret_id to get a valid token. If a cached token is expired or about to expire the Vault client will automatically login and get a new token.

Example configuration

---
# Note: All paths may be absolute or relative. If they are given relative, it is
#       from the cwd where fotoobo has been run.

# The path to a inventory file
inventory: inventory.yaml

# Hide the fotoobo logo
no_logo: false

# Configure how fotoobo logs
# - Each section ("log_file", "log_console" and "log_syslog") can be commented out
#   to disable this output completely
# - The log level given on the command line will overwrite all given log-levels for
#   each output configuration.
logging:
    # The log level
    level: INFO

    # Log to the console
    log_console:

    # The file where fotoobo should log to
    log_file:
        name: fotoobo.log

    # Log to a syslog server
#    log_syslog:
#        host: localhost
#        port: 514
#        protocol: UDP   # UDP or TCP

    # If you need more complex logging, provide a python logging configuration
    # by yourself. See the "logging-config.yaml.sample" for more information.
    # NOTE: This will overwrite all the above settings!
#    log_configuration_file: "logging-config.yaml"


# Configure how fotoobo handles audit logs
# Each section ("log_file", "log_console" and "log_syslog") can be commented out
# to disable this output completely
# NOTE: If you have given a log_configuration_file above, the options given here have no effect
#audit_logging:
#    # File to log audit logs to
#    log_file:
#        name: fotoobo_audit.log
#
#    # Syslog server to log audit logs to
#    log_syslog:
#        host: localhost
#        port: 514
#        protocol: UDP   # UDP or TCP


# Configure the Hashicorp Vault service
# Instead of storing credentials in the inventory file you may use VAULT as a placeholder. All asset
# attributes that are VAULT will be retreived from the Hashicorp Vault service specified here.
# The Hashicorp Vault service will use approle login to get the data.
# We may also read the role_id and secret_id from the system environment. This makes it a little bit
# more secure.
vault:
    url: https://vault.local
    ssl_verify: false
    namespace: vault_namespace
    data_path: /v1/kv/data/fotoobo
    role_id: ...
    secret_id: ...
    token_file: ~/.cache/token.key