ansible-navigator settings

The ansible-navigator settings file

Settings for ansible-navigator can be provided on the command line, set using an environment variable or specified in a settings file.

The settings file name and path can be specified with an environment variable or it can be placed in one of two default directories.

Currently the following are checked and the first match is used:

  • ANSIBLE_NAVIGATOR_CONFIG (settings file path environment variable if set)

  • ./ansible-navigator.<ext> (project directory) (NOTE: no dot in the file name)

  • ~/.ansible-navigator.<ext> (home directory) (NOTE: note the dot in the file name)

Note

  • The settings file can be in JSON or YAML format.

  • For settings in JSON format, the extension must be .json.

  • For settings in YAML format, the extension must be .yml or .yaml.

  • The project and home directories can only contain one settings file each.

  • If more than one settings file is found in either directory, it will result in an error.

You can copy the example settings file below into one of those paths to start your ansible-navigator settings file.

---
ansible-navigator:
#   ansible:
#     config: /tmp/ansible.cfg
#     cmdline: "--forks 15"
#     inventories:
#     - /tmp/test_inventory.yml
#     playbook: /tmp/test_playbook.yml
#
#   ansible-runner:
#     artifact-dir: /tmp/test1
#     rotate-artifacts-count: 10
#     timeout: 300
#
#   app: run
#
#   collection-doc-cache-path: /tmp/cache.db
#
#   color:
#     enable: False
#     osc4: False
#
#   documentation:
#     plugin:
#       name: shell
#       type: become
#
#   editor:
#     command: vim_from_setting
#     console: False
#
#   exec:
#     shell: False
#     command: /bin/foo
#
#   execution-environment:
#     container-engine: podman
#     enabled: False
#     environment-variables:
#       pass:
#         - ONE
#         - TWO
#         - THREE
#       set:
#         KEY1: VALUE1
#         KEY2: VALUE2
#         KEY3: VALUE3
#     image: test_image:latest
#     pull-policy: never
#     volume-mounts:
#     - src: "/test1"
#       dest: "/test1"
#       label: "Z"
#     container-options:
#     - "--net=host"
#
#   help-config: True
#
#   help-doc: True
#
#   help-inventory: True
#
#   help-playbook: False
#
#   inventory-columns:
#     - ansible_network_os
#     - ansible_network_cli_ssh_type
#     - ansible_connection
#
  logging:
    level: critical
#     append: False
#     file: /tmp/log.txt
#
#   mode: stdout
#
#   playbook-artifact:
#     enable: True
#     replay: /tmp/test_artifact.json
#     save-as: /tmp/test_artifact.json

The following table describes all available settings.

General parameters

Name

Description

Settings

ansible-runner-artifact-dir

The directory path to store artifacts generated by ansible-runner

Default: No default value set
CLI: --rad or --ansible-runner-artifact-dir
ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ARTIFACT_DIR
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-runner:
artifact-dir:

ansible-runner-rotate-artifacts-count

Keep ansible-runner artifact directories, for last n runs, if set to 0 artifact directories won’t be deleted

Default: No default value set
CLI: --rac or --ansible-runner-rotate-artifacts-count
ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ROTATE_ARTIFACTS_COUNT
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-runner:
rotate-artifacts-count:

ansible-runner-timeout

The timeout value after which ansible-runner willforce stop the execution

Default: No default value set
CLI: --rt or --ansible-runner-timeout
ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_TIMEOUT
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-runner:
timeout:

app

Subcommands

Choices: ‘collections’, ‘config’, ‘doc’, ‘exec’, ‘images’, ‘inventory’, ‘replay’, ‘run’ or ‘welcome’
Default: welcome
CLI: positional
ENV: ANSIBLE_NAVIGATOR_APP
Settings file:

.. code-block:: yaml

ansible-navigator:
app:

cmdline

Extra parameters passed to the corresponding command

Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_CMDLINE
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
cmdline:

collection-doc-cache-path

The path to collection doc cache

Default: $HOME/.cache/ansible-navigator/collection_doc_cache.db
CLI: --cdcp or --collection-doc-cache-path
ENV: ANSIBLE_NAVIGATOR_COLLECTION_DOC_CACHE_PATH
Settings file:

.. code-block:: yaml

ansible-navigator:
collection-doc-cache-path:

container-engine

Specify the container engine (auto=podman then docker)

Choices: ‘auto’, ‘podman’ or ‘docker’
Default: auto
CLI: --ce or --container-engine
ENV: ANSIBLE_NAVIGATOR_CONTAINER_ENGINE
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
container-engine:

container-options

Extra parameters passed to the container engine command

Default: No default value set
CLI: --co or --container-options
ENV: ANSIBLE_NAVIGATOR_CONTAINER_OPTIONS
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
container-options:

display-color

Enable the use of color in the display

Choices: ‘True’ or ‘False’
Default: True
CLI: --dc or --display-color
ENV: NO_COLOR
Settings file:

.. code-block:: yaml

ansible-navigator:
color:
enable:

editor-command

Specify the editor command

Default: vi +{line_number} {filename}
CLI: --ecmd or --editor-command
ENV: ANSIBLE_NAVIGATOR_EDITOR_COMMAND
Settings file:

.. code-block:: yaml

ansible-navigator:
editor:
command:

editor-console

Specify if the editor is console based

Choices: ‘True’ or ‘False’
Default: True
CLI: --econ or --editor-console
ENV: ANSIBLE_NAVIGATOR_EDITOR_CONSOLE
Settings file:

.. code-block:: yaml

ansible-navigator:
editor:
console:

execution-environment

Enable or disable the use of an execution environment

Choices: ‘True’ or ‘False’
Default: True
CLI: --ee or --execution-environment
ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
enabled:

execution-environment-image

Specify the name of the execution environment image

Default: quay.io/ansible/creator-ee:v0.2.0
CLI: --eei or --execution-environment-image
ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_IMAGE
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
image:

execution-environment-volume-mounts

Specify volume to be bind mounted within an execution environment (–eev /home/user/test:/home/user/test:Z)

Default: No default value set
CLI: --eev or --execution-environment-volume-mounts
ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_VOLUME_MOUNTS
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
volume-mounts:

log-append

Specify if log messages should be appended to an existing log file, otherwise a new log file will be created per session

Choices: ‘True’ or ‘False’
Default: True
CLI: --la or --log-append
ENV: ANSIBLE_NAVIGATOR_LOG_APPEND
Settings file:

.. code-block:: yaml

ansible-navigator:
logging:
append:

log-file

Specify the full path for the ansible-navigator log file

Default: $PWD/ansible-navigator.log
CLI: --lf or --log-file
ENV: ANSIBLE_NAVIGATOR_LOG_FILE
Settings file:

.. code-block:: yaml

ansible-navigator:
logging:
file:

log-level

Specify the ansible-navigator log level

Choices: ‘debug’, ‘info’, ‘warning’, ‘error’ or ‘critical’
Default: warning
CLI: --ll or --log-level
ENV: ANSIBLE_NAVIGATOR_LOG_LEVEL
Settings file:

.. code-block:: yaml

ansible-navigator:
logging:
level:

mode

Specify the user-interface mode

Choices: ‘stdout’ or ‘interactive’
Default: interactive
CLI: -m or --mode
ENV: ANSIBLE_NAVIGATOR_MODE
Settings file:

.. code-block:: yaml

ansible-navigator:
mode:

osc4

Enable or disable terminal color changing support with OSC 4

Choices: ‘True’ or ‘False’
Default: True
CLI: --osc4 or --osc4
ENV: ANSIBLE_NAVIGATOR_OSC4
Settings file:

.. code-block:: yaml

ansible-navigator:
color:
osc4:

pass-environment-variable

Specify an exiting environment variable to be passed through to and set within the execution environment (–penv MY_VAR)

Default: No default value set
CLI: --penv or --pass-environment-variable
ENV: ANSIBLE_NAVIGATOR_PASS_ENVIRONMENT_VARIABLES
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
environment-variables:
pass:

pull-policy

Specify the image pull policy. always:Always pull the image, missing:Pull if not locally available, never:Never pull the image, tag:if the image tag is ‘latest’, always pull the image, otherwise pull if not locally available

Choices: ‘always’, ‘missing’, ‘never’ or ‘tag’
Default: tag
CLI: --pp or --pull-policy
ENV: ANSIBLE_NAVIGATOR_PULL_POLICY
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
pull-policy:

set-environment-variable

Specify an environment variable and a value to be set within the execution environment (–senv MY_VAR=42)

Default: No default value set
CLI: --senv or --set-environment-variable
ENV: ANSIBLE_NAVIGATOR_SET_ENVIRONMENT_VARIABLES
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
environment-variables:
set:



Subcommand: config

Name

Description

Settings

config

Specify the path to the ansible configuration file

Default: No default value set
CLI: -c or --config
ENV: ANSIBLE_CONFIG
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
config:

help-config

Help options for ansible-config command in stdout mode

Choices: ‘True’ or ‘False’
Default: False
CLI: --hc or --help-config
ENV: ANSIBLE_NAVIGATOR_HELP_CONFIG
Settings file:

.. code-block:: yaml

ansible-navigator:
help-config:


Subcommand: doc

Name

Description

Settings

help-doc

Help options for ansible-doc command in stdout mode

Choices: ‘True’ or ‘False’
Default: False
CLI: --hd or --help-doc
ENV: ANSIBLE_NAVIGATOR_HELP_DOC
Settings file:

.. code-block:: yaml

ansible-navigator:
help-doc:

plugin-name

Specify the plugin name

Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_PLUGIN_NAME
Settings file:

.. code-block:: yaml

ansible-navigator:
documentation:
plugin:
name:

plugin-type

Specify the plugin type, ‘become’, ‘cache’, ‘callback’, ‘cliconf’, ‘connection’, ‘httpapi’, ‘inventory’, ‘lookup’, ‘module’, ‘netconf’, ‘shell’, ‘strategy’ or ‘vars’

Choices: ‘become’, ‘cache’, ‘callback’, ‘cliconf’, ‘connection’, ‘httpapi’, ‘inventory’, ‘lookup’, ‘module’, ‘netconf’, ‘shell’, ‘strategy’ or ‘vars’
Default: module
CLI: -t or --type
ENV: ANSIBLE_NAVIGATOR_PLUGIN_TYPE
Settings file:

.. code-block:: yaml

ansible-navigator:
documentation:
plugin:
type:


Subcommand: exec

Name

Description

Settings

exec-command

Specify the command to run within the execution environment

Default: /bin/bash
CLI: --excmd or --exec-command
ENV: ANSIBLE_NAVIGATOR_EXEC_COMMAND
Settings file:

.. code-block:: yaml

ansible-navigator:
exec:
command:

exec-shell

Specify the exec command should be run in a shell.

Choices: ‘True’ or ‘False’
Default: True
CLI: --exshell or --exec-shell
ENV: ANSIBLE_NAVIGATOR_EXEC_SHELL
Settings file:

.. code-block:: yaml

ansible-navigator:
exec:
shell:


Subcommand: inventory

Name

Description

Settings

help-inventory

Help options for ansible-inventory command in stdout mode

Choices: ‘True’ or ‘False’
Default: False
CLI: --hi or --help-inventory
ENV: ANSIBLE_NAVIGATOR_HELP_INVENTORY
Settings file:

.. code-block:: yaml

ansible-navigator:
help-inventory:

inventory

Specify an inventory file path or comma separated host list

Default: No default value set
CLI: -i or --inventory
ENV: ANSIBLE_NAVIGATOR_INVENTORIES
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
inventories:

inventory-column

Specify a host attribute to show in the inventory view

Default: No default value set
CLI: --ic or --inventory-column
ENV: ANSIBLE_NAVIGATOR_INVENTORY_COLUMNS
Settings file:

.. code-block:: yaml

ansible-navigator:
inventory-columns:


Subcommand: replay

Name

Description

Settings

playbook-artifact-replay

Specify the path for the playbook artifact to replay

Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_REPLAY
Settings file:

.. code-block:: yaml

ansible-navigator:
playbook-artifact:
replay:


Subcommand: run

Name

Description

Settings

help-playbook

Help options for ansible-playbook command in stdout mode

Choices: ‘True’ or ‘False’
Default: False
CLI: --hp or --help-playbook
ENV: ANSIBLE_NAVIGATOR_HELP_PLAYBOOK
Settings file:

.. code-block:: yaml

ansible-navigator:
help-playbook:

inventory

Specify an inventory file path or comma separated host list

Default: No default value set
CLI: -i or --inventory
ENV: ANSIBLE_NAVIGATOR_INVENTORIES
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
inventories:

inventory-column

Specify a host attribute to show in the inventory view

Default: No default value set
CLI: --ic or --inventory-column
ENV: ANSIBLE_NAVIGATOR_INVENTORY_COLUMNS
Settings file:

.. code-block:: yaml

ansible-navigator:
inventory-columns:

playbook

Specify the playbook name

Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
playbook:

playbook-artifact-enable

Enable or disable the creation of artifacts for completed playbooks. Note: not compatible with ‘–mode stdout’ when playbooks require user input

Choices: ‘True’ or ‘False’
Default: True
CLI: --pae or --playbook-artifact-enable
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_ENABLE
Settings file:

.. code-block:: yaml

ansible-navigator:
playbook-artifact:
enable:

playbook-artifact-save-as

Specify the name for artifacts created from completed playbooks

Default: {playbook_dir}/{playbook_name}-artifact-{ts_utc}.json
CLI: --pas or --playbook-artifact-save-as
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_SAVE_AS
Settings file:

.. code-block:: yaml

ansible-navigator:
playbook-artifact:
save-as: