# automatix
Automation wrapper for bash and python commands
# DESCRIPTION
**automatix** is a wrapper for scripted sysadmin tasks. It offers
some useful functionality for easier scripting and having full
control over the automated process.
The idea of **automatix** is to write down all the commands you would
normally type to your commandline or python console into a YAML file.
Then use **automatix** to execute these commands.
There are different modes for **automatix** to work. Without any
parameters automatix will try to execute the specified command
pipeline from the script file until an error occurs or the pipeline
is done. The interactive mode (**-i**) asks for every single
commandline step whether to execute, skip or abort.
Forced mode (**-f**) will also proceed if errors occur.
**automatix** is originally designed for internal //SEIBERT/MEDIA use.
It comes therefore with bundlewrap and teamvault support as well as
the possibility to use your own logging library.
## Warning:
Beware that this tool cannot substitute the system administrators
brain and it needs a responsible handling, since you can do
(and destroy) almost everything with it.
**Automatix** evaluates YAML files and executes defined commands as
shell or python commands. There is no check for harmful commands.
Be aware that this can cause critical damage to your system.
Please use the interactive mode and doublecheck commands before
executing. Usage of automatix is at your own risk!
# INSTALLATION
Automatix requires Python ≥ 3.8.
```
pip install automatix
```
# CONFIGURATION
You can specify a path to a configuration YAML file via the
environment variable **AUTOMATIX_CONFIG**.
Default location is "~/.automatix.cfg.yaml".
### Example: .automatix.cfg.yaml
# Path to scripts directory
script_dir: ~/automatix_script_files
# Global constants for use in pipeline scripts
constants:
apt_update: 'apt-get -qy update'
apt_upgrade: 'DEBIAN_FRONTEND=noninteractive apt-get -qy -o Dpkg::Options::=--force-confold --no-install-recommends upgrade'
apt_full_upgrade: 'DEBIAN_FRONTEND=noninteractive apt-get -qy -o Dpkg::Options::=--force-confold --no-install-recommends full-upgrade'
# Encoding
encoding: utf-8
# Path for shell imports
import_path: '.'
# SSH Command used for remote connections
ssh_cmd: 'ssh {hostname} sudo '
# Temporary directory on remote machines for shell imports
remote_tmp_dir: 'automatix_tmp'
# Logger
logger: mylogger
# Logging library (has to implement the init_logger method)
logging_lib: mylib.logging
# Bundlewrap support, bundlewrap has to be installed (default: false)
bundlewrap: true
# Teamvault / Secret support, bundlewrap-teamvault has to be installed (default: false)
teamvault: true
# SYNOPSIS
**automatix**
\[**--help**|**-h**\]
\[**--systems** \[_SYSTEM1=ADDRESS_OR_NODENAME_ ...\]\]
\[**--vars** \[_VAR1=VALUE1_ ...\]\]
\[**--secrets** \[_SECRET1=SECRETID_ ...\]\]
\[**--vars-file** _VARS_FILE_PATH_ \]
\[**--print-overview**|**-p**\]
\[**--jump-to**|**-j** _JUMP_TO_\]
\[**--steps**|**-s** _STEPS_\]
\[**--interactive**|**-i**\]
\[**--force**|**-f**\]
\[**--debug**|**-d**\]
\[**--**\] **scriptfile**
## OPTIONS
**scriptfile**
: The only required parameter for this tool to work. Use " -- " if
needed to delimit this from argument fields. See **SCRIPTFILE**
section for more information.
**-h**, **--help**
: View help message and exit.
**--systems** _SYSTEM1=ADDRESS_OR_NODENAME_
: Use this to set systems without adding them to the
scriptfile or to overwrite them. You can specify multiple
systems like: --systems v1=string1 v2=string2 v3=string3
**--vars** _VAR1=VALUE1_
: Use this to set vars without adding them to the scriptfile
or to overwrite them. You can specify multiple vars
like: --vars v1=string1 v2=string2 v3=string3
**--secrets** _SECRET1=SECRETID_
: Use this to set secrets without adding them to the
scriptfile or to overwrite them. You can specify multiple
secrets like: --secrets v1=string1 v2=string2 v3=string3 *(only if
teamvault is enabled)*
**--vars-file** _VARS_FILE_PATH_
: Use this to specify a CSV file from where **automatix** reads
systems, variables and secrets. First row must contain the field
types and names. You may also specify an `label` field.
Example: `label,systems:mysystem,vars:myvar`. The automatix script will
be processed for each row sequentially.
**--print-overview**, **-p**
: Just print command pipeline overview with indices then exit without
executing the commandline. Note that the *always pipeline* will be
executed anyway.
**--jump-to** _JUMP_TO_, **-j** _JUMP_TO_
: Jump to step with index _JUMP_TO_ instead of starting at the
beginning. Use **-p** or the output messages to determine the
desired step index. You can use negative numbers to start counting
from the end.
**--steps** _STEPS_, **-s** _STEPS_
: Only execute these steps (comma-separated indices) or exclude steps
by prepending the comma-separated list with "e".
Examples: `-s 1,3,7`, `-s e2`, `-s e0,5,7,2`
**--interactive**, **-i**
: Confirm actions before executing.
**--force**, **-f**
: Try always to proceed (except manual steps), even if errors occur
(no retries).
**--debug**, **-d**
: Activate debug log level.
### EXAMPLE: Usage
automatix -i --systems source=sourcesystem.com target=targetsystem.org -- scriptfile.yaml
## SCRIPTFILE
The **scriptfile** describes your automated process. Therefore it
contains information about systems, variables, secrets and the
command pipeline.
You can provide a path to your **scriptfile** or place your
scriptfile in the predefined directory (see **CONFIGURATION**
section, _script_dir_). The path has precedence over the predefined
directory, if the file exists at both locations.
The **scriptfile** has to contain valid YAML.
### EXAMPLE: scriptfile
name: Migration Server XY
# Systems you like to refer to in pipeline (accessible via 'SYSTEMS.source')
# If Bundlewrap support is activated use node names instead of hostnames or add preceeding 'hostname!'.
require_version: '1.5.0'
systems:
source: sourcesystem.com
target: targetsystem.org
# Custom vars to use in pipeline
vars:
version: 1.2.3
domain: 'bla.mein-test-system'
# Teamvault Secrets, if activated (left: like vars, right: SECRETID_FIELD, FIELD=username|password|file)
secrets:
web_user: v6GQag_username
web_pw: v6GQag_password
# Imports for functions you like to use (path may be modified in configuration)
imports:
- myfunctions.sh
# like command pipeline but will be exectuted always beforehand
always:
- python: |
import mylib as nc
PERSISTENT_VARS.update(locals())
pipeline:
- remote@target: systemctl stop server
- remote@source: zfs snapshot -r tank@before-migration
- manual: Please trigger preparing tasks via webinterface
- myvar=local: curl -L -vvv -k https://{domain}/
- local: echo "1.1.1.1 {domain}" >> /etc/hosts
- sla=python: NODES.source.metadata.get('sla')
- python: |
sla = '{sla}'
if sla == 'gold':
print('Wow that\'s pretty cool. You have SLA Gold.')
else:
print('Oh. Running out of money? SLA Gold is worth it. You should check your wallet.')
PERSISTENT_VARS['sla'] = sla
- cond=python: sla == 'gold'
- cond?local: echo "This command is only executed if sla is gold."
cleanup:
- local: rm temp_files
### FIELDS
**name** _(string)_
: Just a name for the process. Does not do anything.
**require_version** _(string)_
: Minimum required Automatix version for this script to run.
**systems** _(associative array)_
: Define some systems. Value has to be a valid SSH destination like an
IP address or hostname. If Bundlewrap support is enabled, it has to
be a valid and existing Bundlewrap node or group name or you can
preceed your IP or hostname with `hostname!` to define a
non-Bundlewrap system.
You can refer to these systems in the command pipeline in multiple ways:
1) remote@systemname as your command action (see below)
2) via {SYSTEMS.systemname} which will be replaced with the value
3) via NODES.systemname in python actions to use the Bundlewrap node
object (Bundlewrap nodes only, no groups)
**vars** _(associative array)_
: Define some vars. These are accessible in the command pipeline via
{varname}. Note: Only valid Python variable names are allowed.
You can use "*FILE_*" prefix followed by a file path to assign the file
content to the variable.
**secrets** _(associative array)_
: Define teamvault secrets. Value has to be in this format:
_SECRETID_FIELD_. _FIELD_ must be one of username, password or file.
The resolved secret values are accessible in command line via
{secretname}. *(only if teamvault is enabled)*
**imports** _(list)_
: Listed shell files (see **CONFIGURATION** section, _import_path_)
will be sourced before every local or remote command execution.
For remote commands, these files are transferred via tar and ssh to
your home directory on the remote system beforehand and deleted
afterwards. This is meant to define some functions you may need.
**always**, **cleanup** _(list of associative arrays)_
: See **ALWAYS / CLEANUP PIPELINE** section.
**pipeline** _(list of associative arrays)_
: See **PIPELINE** section.
### PIPELINE
Here you define the commands automatix shall execute.
**KEY**: One of these possible command actions:
1) **manual**: Some manual instruction for the user. The user has to
confirm, that automatix may proceed.
2) **local**: Local shell command to execute. Imports will be sourced
beforehand. /bin/bash will be used for execution.
3) **remote@systemname**: Remote shell command to execute. Systemname
has to be a defined system. The command will be run via SSH (without
pseudo-terminal allocation). It uses the standard SSH command.
Therefore your .ssh/config should be respected.
If systemname is a Bundlewrap group, the remote command will be
executed sequentially for every node.
4) **python**: Python code to execute.
* Notice that there are some modules, constants and functions which
are already imported (check command.py): e.g.
`re, subprocess, quote(from shlex)`. The variable `vars` is used
to store the Automatix variables as a dictionary. You can use it
to access or change the variables directly.
* If bundlewrap is enabled, the Bundlewrap repository object is
available via AUTOMATIX_BW_REPO and system node objects are
available via NODES.systemname.
Use `AUTOMATIX_BW_REPO.reload()` to reinitialize the Bundlewrap
repository from the file system. This can be useful for using
newly created nodes (e.g. remote commands).
**ASSIGNMENT**: For **local**, **remote** and **python** action you
can also define a variable to which the output will be assigned.
To do this prefix the desired variablename and = before the action
key, e.g. `myvar=python: NODES.system.hostname`. Be careful when
working with multiline statements. In **python** the first line is
likely to set the variable. All variables will be converted to
strings when used to build commands in following steps.
**CONDITIONS**: You can define the command only to be executed if
your condition variable evaluates to "True" in Python. To achieve this
write the variable name followed by a question mark at the very
beginning like `cond?python: destroy_system()`. Be aware that all
output from **local** or **remote** commands will lead to a
non-empty string which evaluates to "True" in Python, but empty output
will evaluate to "False".
**VALUE**: Your command. Variables will be replaced with Python
format function. Therefore, use curly brackets to refer to variables,
systems, secrets and constants.
Constants are available via CONST.KEY, where KEY is the key of your
constants in your **CONFIGURATION** file. There you can define some
widely used constants.
In most cases its a good idea to define your command in quotes to
avoid parsing errors, but it is not always necessary. Another way is
to use '|' to indicate a _literal scalar block_. There you can even
define whole program structures for python (see example).
#### Escaping in Pipeline
Because automatix uses Python's format() function:
`{` -> `{{`
`}` -> `}}`
Standard YAML escapes (see also https://yaml.org/spec/1.2/spec.html):
`'` -> `''`
`"` -> `\"`
`\ ` -> `\\`
`:` -> Please use quotes (double or single).
### ALWAYS / CLEANUP PIPELINE
Same usage as the 'normal' command pipeline, but will be executed
every time at start of automatix (**always**) or at the end
(**cleanup**) even if aborted (a). The commands are executed without
--interactive flag, independend of the specified parameters.
Intended use case for **always**: python imports or informations that
are needed afterwards and do not change anything on systems.
You want to have these available even if using --jump|-j feature.
Intended use case for **cleanup**: Remove temporary files or artifacts.
## ENVIRONMENT
**AUTOMATIX_CONFIG**: Specify the path to the configuration file.
Default is "~/.automatix.cfg.yaml".
**AUTOMATIX_TIME**: Set this to an arbitrary value to print the times
for the single steps and the whole script.
**ENCODING**: Specify output encoding. Default is "UTF-8".
Additionally you can modify the environment to adjust things to your
needs.
# TIPS & TRICKS
If you want to access variables in **python** action you defined in
preceeding command, you can use the **PERSISTENT_VARS** dictionary
(shortcut: **PVARS**).
This is added to the local scope of **python** actions and the
dictonary keys are also available as attributes.
Examples:
- To make all local variables of the actual command persistent use
`PERSISTENT_VARS.update(locals())`.
- To delete one persistent variable named "myvar" use
`del PERSISTENT_VARS['myvar']`
- To make variable "v2" persistent use `PERSISTENT_VARS['v2'] = v2`
or `PERSISTENT_VARS.v2 = v2`
- Use the shortcut like `PVARS.v2 = v2`
You can use variables in PERSISTENT_VARS also as condition by
using the shortcut and the attribute notation:
- python: PVARS.cond = some_function()
- PVARS.cond?local: echo 'This is only printed if "some_function" evaluates to "True"'
An alternative is to make variables global, but in most cases using
PERSISTENT_VARS is more clean. _**CAUTION: Choosing already existing
(Python) variable names may lead to unexpected behaviour!!!**_ Maybe
you want to check the source code (command.py).
Explanation: automatix is written in Python and uses 'exec' to
execute the command in function context. If you declare variables
globally they remain across commands.
To abort the current automatix and jump to the next batch item you can
raise the `SkipBatchItemException`. For aborting the whole automatix
process raise `AbortException(return_code: int)`. In both cases the
cleanup pipeline is executed. Same is the case for selecting
`a`:abort or `c`:continue when asked (interactive or error).
# BEST PRACTISES
There are different ways to start scripting with **automatix**. The
author's approach is mainly to consider the process and simply write
down, what to do (manual steps for complex or not automated steps)
and which commands to use.
Then start **automatix** in interactive mode (-i) and adjust the
single steps one by one. Replace manual steps, if suitable. Whenever
adjustment is needed, abort, adjust and restart **automatix** with
jump (-j) to the adjusted step.
Repeat this procedure to automate more and more and increase quality,
whenever you feel like it.
Consider to put often used paths or code sequences in automatix
variables for better readability.
Do the same with variable content like URLs, to make it possible to
overwrite it by command line options. Where ever possible prefer to
use functions to determine already available information, such as BW
metadata, instead of defining things explicitly. This will make
things easier when using the script with different systems /
parameters.
Preferred way of using **automatix** is to put often used and complex
algorithms in shell functions or python libraries (shelllib/pylib)
and import them. Advantage of this approach is that you can use your
implemented functions multiple times and build up a toolbox of nice
functionality over time.
# NOTES
**Manual steps** will always cause automatix to stop and wait for
user input.
Be careful with **assignments** containing line breaks (echo, ...).
Using the variables may lead to unexpected behaviour or errors.
Assignments containing **null bytes** are currently not supported.
Because the **always** pipeline should not change anything, aborting
while running this pipeline will not trigger a cleanup.
If you want to abort the **pipeline** without triggering the
**cleanup** pipeline, use CRTL+C.
While **aborting remote functions** (via imports), automatix is not
able to determine still running processes invoked by the function,
because it only checks the processes for the commands (in this case
the function name) which is called in the pipeline.
# EXTRAS
## Bash completion (experimental)
Automatix supports bash completion for parameters and the script directory via [argcomplete](https://github.com/kislyuk/argcomplete).
Therefor follow the installation instructions for argcomplete, which is at the current time
pip install argcomplete
and either global activation via executing
activate-global-python-argcomplete
or activation for automatix (e.g. in `.bashrc`)
eval "$(register-python-argcomplete automatix)"
Automatix will recognize the installed module and offer the completion automatically.
Raw data
{
"_id": null,
"home_page": "https://github.com/seibert-media/automatix",
"name": "automatix",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "bash,shell,command,automation,process,wrapper,devops,system administration",
"author": "Johannes Paul, //SEIBERT/MEDIA GmbH",
"author_email": "jpaul@seibert-media.net",
"download_url": "https://files.pythonhosted.org/packages/29/57/6d8e1e1668a17979289148b538b4b7df720ad26464540e4ebc4d665e040e/automatix-1.13.0.tar.gz",
"platform": null,
"description": "# automatix\nAutomation wrapper for bash and python commands\n\n\n# DESCRIPTION\n\n**automatix** is a wrapper for scripted sysadmin tasks. It offers\n some useful functionality for easier scripting and having full\n control over the automated process.\n\nThe idea of **automatix** is to write down all the commands you would\n normally type to your commandline or python console into a YAML file.\n Then use **automatix** to execute these commands. \n\nThere are different modes for **automatix** to work. Without any\n parameters automatix will try to execute the specified command\n pipeline from the script file until an error occurs or the pipeline\n is done. The interactive mode (**-i**) asks for every single\n commandline step whether to execute, skip or abort.\n Forced mode (**-f**) will also proceed if errors occur.\n\n**automatix** is originally designed for internal //SEIBERT/MEDIA use.\n It comes therefore with bundlewrap and teamvault support as well as\n the possibility to use your own logging library.\n\n## Warning:\n\nBeware that this tool cannot substitute the system administrators\n brain and it needs a responsible handling, since you can do\n (and destroy) almost everything with it.\n\n**Automatix** evaluates YAML files and executes defined commands as\n shell or python commands. There is no check for harmful commands.\n Be aware that this can cause critical damage to your system.\n\nPlease use the interactive mode and doublecheck commands before\n executing. Usage of automatix is at your own risk!\n\n\n# INSTALLATION\n\nAutomatix requires Python ≥ 3.8.\n\n```\npip install automatix\n```\n\n# CONFIGURATION\n\nYou can specify a path to a configuration YAML file via the\n environment variable **AUTOMATIX_CONFIG**.\nDefault location is \"~/.automatix.cfg.yaml\".\n\n### Example: .automatix.cfg.yaml\n\n # Path to scripts directory\n script_dir: ~/automatix_script_files\n \n # Global constants for use in pipeline scripts\n constants:\n apt_update: 'apt-get -qy update'\n apt_upgrade: 'DEBIAN_FRONTEND=noninteractive apt-get -qy -o Dpkg::Options::=--force-confold --no-install-recommends upgrade'\n apt_full_upgrade: 'DEBIAN_FRONTEND=noninteractive apt-get -qy -o Dpkg::Options::=--force-confold --no-install-recommends full-upgrade'\n \n # Encoding\n encoding: utf-8\n \n # Path for shell imports\n import_path: '.'\n \n # SSH Command used for remote connections\n ssh_cmd: 'ssh {hostname} sudo '\n \n # Temporary directory on remote machines for shell imports\n remote_tmp_dir: 'automatix_tmp'\n \n # Logger\n logger: mylogger\n \n # Logging library (has to implement the init_logger method)\n logging_lib: mylib.logging\n \n # Bundlewrap support, bundlewrap has to be installed (default: false)\n bundlewrap: true\n \n # Teamvault / Secret support, bundlewrap-teamvault has to be installed (default: false)\n teamvault: true\n\n# SYNOPSIS\n\n**automatix**\n \\[**--help**|**-h**\\]\n \\[**--systems** \\[_SYSTEM1=ADDRESS_OR_NODENAME_ ...\\]\\]\n \\[**--vars** \\[_VAR1=VALUE1_ ...\\]\\]\n \\[**--secrets** \\[_SECRET1=SECRETID_ ...\\]\\]\n \\[**--vars-file** _VARS_FILE_PATH_ \\]\n \\[**--print-overview**|**-p**\\]\n \\[**--jump-to**|**-j** _JUMP_TO_\\]\n \\[**--steps**|**-s** _STEPS_\\]\n \\[**--interactive**|**-i**\\]\n \\[**--force**|**-f**\\]\n \\[**--debug**|**-d**\\]\n \\[**--**\\] **scriptfile**\n\n\n## OPTIONS\n\n**scriptfile**\n: The only required parameter for this tool to work. Use \" -- \" if\n needed to delimit this from argument fields. See **SCRIPTFILE**\n section for more information.\n\n**-h**, **--help**\n: View help message and exit.\n\n**--systems** _SYSTEM1=ADDRESS_OR_NODENAME_\n: Use this to set systems without adding them to the\n scriptfile or to overwrite them. You can specify multiple\n systems like: --systems v1=string1 v2=string2 v3=string3\n \n**--vars** _VAR1=VALUE1_\n: Use this to set vars without adding them to the scriptfile\n or to overwrite them. You can specify multiple vars\n like: --vars v1=string1 v2=string2 v3=string3\n \n**--secrets** _SECRET1=SECRETID_\n: Use this to set secrets without adding them to the\n scriptfile or to overwrite them. You can specify multiple\n secrets like: --secrets v1=string1 v2=string2 v3=string3 *(only if\n teamvault is enabled)*\n \n**--vars-file** _VARS_FILE_PATH_\n: Use this to specify a CSV file from where **automatix** reads\n systems, variables and secrets. First row must contain the field\n types and names. You may also specify an `label` field.\n Example: `label,systems:mysystem,vars:myvar`. The automatix script will\n be processed for each row sequentially.\n \n**--print-overview**, **-p**\n: Just print command pipeline overview with indices then exit without\n executing the commandline. Note that the *always pipeline* will be\n executed anyway.\n\n**--jump-to** _JUMP_TO_, **-j** _JUMP_TO_\n: Jump to step with index _JUMP_TO_ instead of starting at the\n beginning. Use **-p** or the output messages to determine the\n desired step index. You can use negative numbers to start counting\n from the end.\n\n**--steps** _STEPS_, **-s** _STEPS_\n: Only execute these steps (comma-separated indices) or exclude steps\n by prepending the comma-separated list with \"e\".\n Examples: `-s 1,3,7`, `-s e2`, `-s e0,5,7,2`\n\n**--interactive**, **-i**\n: Confirm actions before executing.\n \n**--force**, **-f**\n: Try always to proceed (except manual steps), even if errors occur\n (no retries).\n\n**--debug**, **-d**\n: Activate debug log level.\n\n\n### EXAMPLE: Usage\n\n automatix -i --systems source=sourcesystem.com target=targetsystem.org -- scriptfile.yaml\n\n\n## SCRIPTFILE\n\nThe **scriptfile** describes your automated process. Therefore it\n contains information about systems, variables, secrets and the\n command pipeline.\n\nYou can provide a path to your **scriptfile** or place your\n scriptfile in the predefined directory (see **CONFIGURATION**\n section, _script_dir_). The path has precedence over the predefined\n directory, if the file exists at both locations.\n\nThe **scriptfile** has to contain valid YAML.\n\n### EXAMPLE: scriptfile\n \n name: Migration Server XY\n # Systems you like to refer to in pipeline (accessible via 'SYSTEMS.source')\n # If Bundlewrap support is activated use node names instead of hostnames or add preceeding 'hostname!'.\n require_version: '1.5.0'\n systems:\n source: sourcesystem.com\n target: targetsystem.org\n # Custom vars to use in pipeline\n vars:\n version: 1.2.3\n domain: 'bla.mein-test-system'\n # Teamvault Secrets, if activated (left: like vars, right: SECRETID_FIELD, FIELD=username|password|file)\n secrets:\n web_user: v6GQag_username\n web_pw: v6GQag_password\n # Imports for functions you like to use (path may be modified in configuration)\n imports:\n - myfunctions.sh\n # like command pipeline but will be exectuted always beforehand\n always:\n - python: |\n import mylib as nc\n PERSISTENT_VARS.update(locals())\n pipeline:\n - remote@target: systemctl stop server\n - remote@source: zfs snapshot -r tank@before-migration\n - manual: Please trigger preparing tasks via webinterface\n - myvar=local: curl -L -vvv -k https://{domain}/\n - local: echo \"1.1.1.1 {domain}\" >> /etc/hosts\n - sla=python: NODES.source.metadata.get('sla')\n - python: |\n sla = '{sla}'\n if sla == 'gold':\n print('Wow that\\'s pretty cool. You have SLA Gold.')\n else:\n print('Oh. Running out of money? SLA Gold is worth it. You should check your wallet.')\n PERSISTENT_VARS['sla'] = sla\n - cond=python: sla == 'gold'\n - cond?local: echo \"This command is only executed if sla is gold.\"\n cleanup:\n - local: rm temp_files\n\n\n### FIELDS\n\n**name** _(string)_\n: Just a name for the process. Does not do anything.\n\n**require_version** _(string)_\n: Minimum required Automatix version for this script to run.\n\n**systems** _(associative array)_\n: Define some systems. Value has to be a valid SSH destination like an\n IP address or hostname. If Bundlewrap support is enabled, it has to\n be a valid and existing Bundlewrap node or group name or you can \n preceed your IP or hostname with `hostname!` to define a\n non-Bundlewrap system.\nYou can refer to these systems in the command pipeline in multiple ways:\n\n1) remote@systemname as your command action (see below)\n\n2) via {SYSTEMS.systemname} which will be replaced with the value\n\n3) via NODES.systemname in python actions to use the Bundlewrap node\n object (Bundlewrap nodes only, no groups)\n\n**vars** _(associative array)_\n: Define some vars. These are accessible in the command pipeline via\n {varname}. Note: Only valid Python variable names are allowed.\n You can use \"*FILE_*\" prefix followed by a file path to assign the file\n content to the variable.\n\n**secrets** _(associative array)_\n: Define teamvault secrets. Value has to be in this format:\n _SECRETID_FIELD_. _FIELD_ must be one of username, password or file.\n The resolved secret values are accessible in command line via\n {secretname}. *(only if teamvault is enabled)*\n\n**imports** _(list)_\n: Listed shell files (see **CONFIGURATION** section, _import_path_)\n will be sourced before every local or remote command execution.\n For remote commands, these files are transferred via tar and ssh to\n your home directory on the remote system beforehand and deleted\n afterwards. This is meant to define some functions you may need.\n\n**always**, **cleanup** _(list of associative arrays)_\n: See **ALWAYS / CLEANUP PIPELINE** section.\n\n**pipeline** _(list of associative arrays)_\n: See **PIPELINE** section.\n\n### PIPELINE\n\nHere you define the commands automatix shall execute.\n\n**KEY**: One of these possible command actions:\n\n1) **manual**: Some manual instruction for the user. The user has to\n confirm, that automatix may proceed.\n\n2) **local**: Local shell command to execute. Imports will be sourced\n beforehand. /bin/bash will be used for execution.\n\n3) **remote@systemname**: Remote shell command to execute. Systemname\n has to be a defined system. The command will be run via SSH (without\n pseudo-terminal allocation). It uses the standard SSH command.\n Therefore your .ssh/config should be respected.\n If systemname is a Bundlewrap group, the remote command will be\n executed sequentially for every node.\n\n4) **python**: Python code to execute.\n * Notice that there are some modules, constants and functions which\n are already imported (check command.py): e.g.\n `re, subprocess, quote(from shlex)`. The variable `vars` is used\n to store the Automatix variables as a dictionary. You can use it \n to access or change the variables directly.\n * If bundlewrap is enabled, the Bundlewrap repository object is\n available via AUTOMATIX_BW_REPO and system node objects are\n available via NODES.systemname.\n Use `AUTOMATIX_BW_REPO.reload()` to reinitialize the Bundlewrap \n repository from the file system. This can be useful for using\n newly created nodes (e.g. remote commands). \n \n\n**ASSIGNMENT**: For **local**, **remote** and **python** action you\n can also define a variable to which the output will be assigned.\n To do this prefix the desired variablename and = before the action\n key, e.g. `myvar=python: NODES.system.hostname`. Be careful when\n working with multiline statements. In **python** the first line is\n likely to set the variable. All variables will be converted to\n strings when used to build commands in following steps.\n \n**CONDITIONS**: You can define the command only to be executed if\n your condition variable evaluates to \"True\" in Python. To achieve this\n write the variable name followed by a question mark at the very\n beginning like `cond?python: destroy_system()`. Be aware that all\n output from **local** or **remote** commands will lead to a\n non-empty string which evaluates to \"True\" in Python, but empty output\n will evaluate to \"False\".\n\n**VALUE**: Your command. Variables will be replaced with Python\n format function. Therefore, use curly brackets to refer to variables,\n systems, secrets and constants.\n\nConstants are available via CONST.KEY, where KEY is the key of your\n constants in your **CONFIGURATION** file. There you can define some\n widely used constants.\n\nIn most cases its a good idea to define your command in quotes to\n avoid parsing errors, but it is not always necessary. Another way is\n to use '|' to indicate a _literal scalar block_. There you can even\n define whole program structures for python (see example).\n\n#### Escaping in Pipeline\n\nBecause automatix uses Python's format() function: \n`{` -> `{{` \n`}` -> `}}` \n\nStandard YAML escapes (see also https://yaml.org/spec/1.2/spec.html): \n`'` -> `''` \n`\"` -> `\\\"` \n`\\ ` -> `\\\\` \n`:` -> Please use quotes (double or single). \n\n\n### ALWAYS / CLEANUP PIPELINE\n\nSame usage as the 'normal' command pipeline, but will be executed\n every time at start of automatix (**always**) or at the end\n (**cleanup**) even if aborted (a). The commands are executed without\n --interactive flag, independend of the specified parameters.\n\nIntended use case for **always**: python imports or informations that\n are needed afterwards and do not change anything on systems.\n You want to have these available even if using --jump|-j feature.\n\nIntended use case for **cleanup**: Remove temporary files or artifacts.\n\n\n## ENVIRONMENT\n\n**AUTOMATIX_CONFIG**: Specify the path to the configuration file.\n Default is \"~/.automatix.cfg.yaml\". \n\n**AUTOMATIX_TIME**: Set this to an arbitrary value to print the times\n for the single steps and the whole script.\n\n**ENCODING**: Specify output encoding. Default is \"UTF-8\". \n\nAdditionally you can modify the environment to adjust things to your\n needs.\n\n\n# TIPS & TRICKS\n\nIf you want to access variables in **python** action you defined in\npreceeding command, you can use the **PERSISTENT_VARS** dictionary\n(shortcut: **PVARS**).\nThis is added to the local scope of **python** actions and the\ndictonary keys are also available as attributes.\n Examples:\n- To make all local variables of the actual command persistent use\n `PERSISTENT_VARS.update(locals())`.\n- To delete one persistent variable named \"myvar\" use\n `del PERSISTENT_VARS['myvar']`\n- To make variable \"v2\" persistent use `PERSISTENT_VARS['v2'] = v2`\n or `PERSISTENT_VARS.v2 = v2`\n- Use the shortcut like `PVARS.v2 = v2`\n\nYou can use variables in PERSISTENT_VARS also as condition by\nusing the shortcut and the attribute notation:\n \n - python: PVARS.cond = some_function()\n - PVARS.cond?local: echo 'This is only printed if \"some_function\" evaluates to \"True\"'\n\nAn alternative is to make variables global, but in most cases using\n PERSISTENT_VARS is more clean. _**CAUTION: Choosing already existing\n (Python) variable names may lead to unexpected behaviour!!!**_ Maybe\n you want to check the source code (command.py). \nExplanation: automatix is written in Python and uses 'exec' to\n execute the command in function context. If you declare variables\n globally they remain across commands.\n\nTo abort the current automatix and jump to the next batch item you can\n raise the `SkipBatchItemException`. For aborting the whole automatix\n process raise `AbortException(return_code: int)`. In both cases the\n cleanup pipeline is executed. Same is the case for selecting\n `a`:abort or `c`:continue when asked (interactive or error).\n \n\n# BEST PRACTISES\n\nThere are different ways to start scripting with **automatix**. The\n author's approach is mainly to consider the process and simply write\n down, what to do (manual steps for complex or not automated steps)\n and which commands to use. \nThen start **automatix** in interactive mode (-i) and adjust the\n single steps one by one. Replace manual steps, if suitable. Whenever\n adjustment is needed, abort, adjust and restart **automatix** with\n jump (-j) to the adjusted step. \nRepeat this procedure to automate more and more and increase quality,\n whenever you feel like it.\n\nConsider to put often used paths or code sequences in automatix\n variables for better readability. \nDo the same with variable content like URLs, to make it possible to\n overwrite it by command line options. Where ever possible prefer to\n use functions to determine already available information, such as BW\n metadata, instead of defining things explicitly. This will make\n things easier when using the script with different systems /\n parameters.\n\nPreferred way of using **automatix** is to put often used and complex\n algorithms in shell functions or python libraries (shelllib/pylib)\n and import them. Advantage of this approach is that you can use your\n implemented functions multiple times and build up a toolbox of nice\n functionality over time.\n\n\n# NOTES\n\n**Manual steps** will always cause automatix to stop and wait for\n user input.\n\nBe careful with **assignments** containing line breaks (echo, ...).\n Using the variables may lead to unexpected behaviour or errors.\n\nAssignments containing **null bytes** are currently not supported.\n\nBecause the **always** pipeline should not change anything, aborting\n while running this pipeline will not trigger a cleanup.\n\nIf you want to abort the **pipeline** without triggering the\n **cleanup** pipeline, use CRTL+C.\n\nWhile **aborting remote functions** (via imports), automatix is not\n able to determine still running processes invoked by the function,\n because it only checks the processes for the commands (in this case\n the function name) which is called in the pipeline.\n\n# EXTRAS\n\n## Bash completion (experimental)\nAutomatix supports bash completion for parameters and the script directory via [argcomplete](https://github.com/kislyuk/argcomplete).\n\nTherefor follow the installation instructions for argcomplete, which is at the current time\n\n pip install argcomplete\n\nand either global activation via executing\n\n activate-global-python-argcomplete\n\nor activation for automatix (e.g. in `.bashrc`)\n\n eval \"$(register-python-argcomplete automatix)\"\n\nAutomatix will recognize the installed module and offer the completion automatically.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automation wrapper for bash and python commands",
"version": "1.13.0",
"project_urls": {
"Homepage": "https://github.com/seibert-media/automatix"
},
"split_keywords": [
"bash",
"shell",
"command",
"automation",
"process",
"wrapper",
"devops",
"system administration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "00e219d5721acf29b40e4942060b4551d9f8032fd6793b161ff44bd2a4a69d45",
"md5": "4e75e391d57cd6fdcaf9b42d7c1403c3",
"sha256": "21cb64d59dc0b8d5f06af380e0feebe6b21018fcbff4261a390e93e2a5b16416"
},
"downloads": -1,
"filename": "automatix-1.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e75e391d57cd6fdcaf9b42d7c1403c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23512,
"upload_time": "2023-11-24T15:53:36",
"upload_time_iso_8601": "2023-11-24T15:53:36.182904Z",
"url": "https://files.pythonhosted.org/packages/00/e2/19d5721acf29b40e4942060b4551d9f8032fd6793b161ff44bd2a4a69d45/automatix-1.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "29576d8e1e1668a17979289148b538b4b7df720ad26464540e4ebc4d665e040e",
"md5": "51eeab65c140f6cfd87230967d912e73",
"sha256": "7760def0d05f9c4fcadbf450bda9aec3e10546aa43eccd5c9d528a318f9dcf68"
},
"downloads": -1,
"filename": "automatix-1.13.0.tar.gz",
"has_sig": false,
"md5_digest": "51eeab65c140f6cfd87230967d912e73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28149,
"upload_time": "2023-11-24T15:53:38",
"upload_time_iso_8601": "2023-11-24T15:53:38.086251Z",
"url": "https://files.pythonhosted.org/packages/29/57/6d8e1e1668a17979289148b538b4b7df720ad26464540e4ebc4d665e040e/automatix-1.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-24 15:53:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "seibert-media",
"github_project": "automatix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "automatix"
}
JSON
