⏩Quickstart Guide

So, you have axiom installed, you're feeling pretty good about yourself, you're 10 minutes away from feeling the power of axiom!

Ensure your build has occurred successfully

If you've followed the installation steps with success, you should have run the axiom-configure script at some point. axiom-configure automatically starts axiom-build. During this time, Packer by HashiCorp will create an image. You should notice "Shutting down gracefully... Creating snapshot....".

You should have a valid build in your account now, if, in doubt, you can run axiom-build and create a new base snapshot just in case!

You can also manually edit your account details such as API key, image id, CPU, RAM etc, in the profile.json you just created cat ~/.axiom/accounts/personal.json.

If you have a valid build in your account, skip to axiom-init.

ax configure

Setup and configure the axiom controller and validate cloud account 💻

ax configure

Description:
Examples:
  axiom-configure --setup # kick off Ax configuration wizard
  axiom-configure --shell zsh # Set default shell to zsh via command line
  axiom-configure --config <personal.json file> # Use personal.json from a file for account setup
  axiom-configure --config <personal.json string> # Use personal.json data supplied by command-line for account setup (must be vaild personal.json data wrapped in single quotes)
  axiom-configure --shell bash --unattended --config <path to personal.json file>  # Use bash for default shell, do not promot, use personal.json data from file for axiom setup
Usage:
  --setup (optional)
    Start axiom-configure wizard, install dependencies, kick off axiom-account-setup and axiom-build
  --config <axiom.json data>
    Setup account with data from file or supplied from the command line (must be vaild data from a personal.json axiom file)
  --unattended (optional)
    Avoid any promots, defaults to Oh My Zsh unless --shell argument is also provided
  --shell <bash, zsh, omz (Oh My Zsh)> (optional)
    Add axiom to path, backup .zshrc/.bashrc to .zshrcbak/.bashrcbak
  --debug (optional)
    Enable debug mode (VERY VERBOSE!)
  --help
    Display this help menu

ax configure --setup

You can provide your config file before or after running axiom-configure.

axiom-configure --setup --shell bash --unattended --config ~/.axiom/accounts/do.json

---

---

ax build

Pick a Packer provisioner 🐣

You must run axiom-configure before anything else. This creates your axiom.json file which is required by other commands.

Description:
  axiom-build supports both legacy Packer JSON files as well as the new HCL format
  axiom-build combines a cloud provider's Builder (~/.axiom/images/$format/builders) with a Provisioner (~/.axiom/images/$format/provisioners)
  to generate the final Packer file (~/.axiom/images/$format/axiom.$format)
  Using Packer, axiom-build creates an image with the tools pre-installed, as defined by the chosen Provisioner
  choose between multiple Provisioners (barebones, default, reconftw, and extras) or bring your own (custom)

  axiom-build adds your SSH key to the image, allowing you to connect to instances created using the image
  by default, it creates and uses an SSH key located at ~/.ssh/axiom_ssh.pub, but you can specify a custom SSH key if needed
Examples:
  axiom-build --run # Kick off the interactive build wizard
  axiom-build default # Build a new Packer image using the Default Provisioner
  axiom-build barebones --debug # Build a new Packer image using the Barebones Provisioner, run with --debug
  axiom-build --ssh-key ~/.ssh/id_rsa.pub # Set a custom SSH key (default is SSH key in ~/.ssh/axiom_ssh.pub)
Usage:
  <provisioner> (optional)
    Name of provisioner to build, options are barebones, default, reconftw, extras or custom (provisioner must be located in ~/.axiom/images/$format/provisioners)
  --run (optional)
    Start axiom-build setup wizard
  --legacy (optional)
    Use legacy Packer JSON Builder and Provisioner instead of pkr.hcl
  --ssh-key <file to pub key> (optional)
    Build the image using a custom SSH key (instead of using the default ssh key axiom creates ~/.ssh/axiom_ssh.pub)
  --debug (optional)
    Enable debug mode (VERY VERBOSE!)
  --help (optional)
    Display this help menu

axiom-build default

You can provide your provisioner inline or after running axiom-build.

We currently offer four different base provisioner files, and 2 custom provisioner file to build images.

• Default is our latest iteration of axiom provisioners. It comes with many tools installed and has been optimized for readability. Recommended for axiom-fleet.

• ReconFTW provisioner includes all tools in ReconFTW and works with most modules. Recommended for ReconFTW.

• Barebones is our decently secure base install, comes with Docker, Go-lang, Interlace and nmap installed. Recommended for templating.

• Extras has more tools installed than our Default provisioner

To use your own Provisioner, read Bring Your Own Provisioner.

ax images

Manage images/snapshots with axiom-images 💿

Description:
  Manage images created by 'axiom-build' or 'axiom-images' with 'axiom-images'!
  After creating an image, list all images on the account 'axiom-images ls'
  Delete images on the account that are no longer needed 'axiom-images rm $image_name'
  Create a new image/snapshot from a deployed instance with 'axiom-images create' (list all deployed instances with 'axiom-ls')
  After the new image is created, or to switch to a different image on the account, select it with 'axiom-images select $image_name' to use for 'axiom-init/axiom-fleet'!
Examples:
  axiom-images ls # List all images on the account
  axiom-images get # Print details from ~/.axiom/axiom.sjon
  axiom-images rm axiom-default-1709878237 # Delete image named axiom-default-1709878237 from the account
  axiom-images create # Start 'axiom-images' image creation wizard
  axiom-images create testy01 # Skip image creation wizard and instead create image from testy01 instance
  axiom-images select axiom-barebones-1709944106 # Select image named axiom-barebones-1709944106 to use with future 'axiom-init/axiom-fleet'
Usage:
  ls (optional)
    List all images on the account 'axiom-images ls'
  get (optional)
    Print information about current account, equivalent to (cat ~/.axiom/axiom.json) 'axiom-images get'
  rm <required image name>
    Specify an image by name to delete (must be an image name from 'axiom-images ls')
  create <optional instance name>
    Kick off axiom-images creation wizard or specify an instance to create an image from 'axiom-images create $instance_name'
  select <required image name>
    Select a new image to use for future 'axiom-init/axiom-fleet', replaces 'imageid' in ~/.axiom/axiom.json with new 'imageid' (must be an image name from 'axiom-images ls')
  --debug (optional)
    Enable debug mode (VERY VERBOSE!)
  --help (optional)
    Display this help menu

axiom-images ls # List available images
axiom-images use <image name> # Replace image used for axiom-init/axiom-fleet with user provided image name 
axiom-images rm <image name> # Delete image by name
ax image create # kick off image creation wizard. Make a snapshot of a running ax instance to use for future ax init/ax fleet

---

ax init

Initialize a single instance 🌱

Description:
  Initialize one axiom instance with differnet options, such as image, region, size and axiom deployment profiles
Examples:
  axiom-init --run # provision instance with random name
  axiom-init --deploy desktop # provision instance with random name, then deploy axiom profile 'desktop'
  axiom-init testy01 # provision instance named testy01
  axiom-init stok01 --region nyc3 --image axiom-default-1635920849 --size s-1vcpu-2gb --deploy desktop --shell
Usage:
  <name> string (optional)
    Name of the instance, supplied as a positional first argument
  --run (optional)
    Create one instance with random name
  --image <image name>
    Manually set the image to use (default is imageid in ~/.axiom/axiom.json)
  --region <region>
    User specified region to use (default is region in ~/.axiom/axiom.json)
  --deploy <profile>
    Deploy a profile after initialization (e.g desktop, openvpn, bbrf, wireguard)
  --shell (optional)
    Connect to instance after initialization
  --size <vm size>
    VM size to use (default is size in ~/.axiom/axiom.json)
  --no-select (optional)
    Dont select instance after initialization (default is to select instance)
  --debug (optional)
    Run with set -xv, warning: very verbose
  --help
    Display this help menu

ax init <name> # Init
ax init --run # Init with random instance name
ax init <name> --deploy=<profile># Init and install deployment profile 

the --deploy option allows you to install a deployment profile (stored in ~/.axiom/profiles/)

---

ax exec

Execute a command against one or many instances 🤖

Description:
  Evaluate shell one-liners or execute single commands on one or more instances in parallel
  Specify the fleet prefix, or let axiom use selected.conf by default (located in ~/.axiom/selected.conf)
  Execute command(s) from a detached tmux session on the remote instances
  Temporarily prevent axiom's SSH key regeneration and instead connect with a cached SSH config (default is ~/.axiom/.sshconfig)
Examples:
  axiom-exec id # Execute command id across all instances currently selected.conf (located in ~/.axiom/selected.conf)
  axiom-exec ifconfig --fleet testy # Execute ifconfig on testy fleet, automatically select all instances in fleet testy
  axiom-exec 'sudo apt dist-upgrade -y' -q --cache --fleet OtherFleet --tmux MySession01 # Quietly execute command(s) inside a detacted tmux session on the remote instances with custom session name
  axiom-exec whoami -q --cache --sshconfig ~/.axiom/log/exec/axiom-exec+1234567890/sshconfig --fleet oldfleet --tmux # Specify the axiom SSH config to use (default is ~/.axiom/.sshconfig)
Usage:
  <commands> required string
    Command(s) to run on the remote axiom instances, multiple commands can be wrapped in single or double quotes, but not required
  -f/--fleet/--file <fleet prefix or list of instances from a file>
    Fleet prefix to execute on (default is ~/.axiom/selected.conf). Automatic wildcard support. Alternatively, can be a list of instances from a file (-f/--fleet/--file myinstances.txt)
  -i/--instance <instance name>
    Single instance to execute on
  --sshconfig <sshconfig_file> (optional string)
    Path to axiom's SSH config (default is ~/.axiom/.sshconfig)
  -q/--quiet (optional)
    Disable progress bar, and reduce verbosity
  --debug (optional)
    Enable debug mode (VERY VERBOSE!)
  --cache (optional)
    Temporarily do not generate SSH config and instead connect with cached SSH config
  --logs (optional)
    Do not delete logs (logs will be stored in ~/.axiom/logs/exec/axiom-exec$TIMESTAMP)
  --quick (optional)
    A faster but less reliable execution
  --skip-preflight (optional)
    Do not automatically remove instances that cant be reached (default removes instances from the queue that cant be reached)
  --preflight-timeout <int>
    Specifies the timeout (in seconds) used when connecting to the SSH server, instead of using the default 5 seconds
  --help
    Display this help menu

  axiom-exec id # Execute command id across all instances currently selected.conf (located in ~/.axiom/selected.conf)
  axiom-exec ifconfig --fleet testy # Execute ifconfig on testy fleet. Automatically select all instances in fleet testy
  axiom-exec sleep "$(($RANDOM % 10))" "&& id &&" echo $HOSTNAME --fleet stok # Evaluate complex one-liners on fleet stok
  axiom-exec 'sudo apt dist-upgrade -y' -q --cache --fleet OtherFleet --tmux MySession01 # Quietly execute command(s) inside a detacted tmux session on the remote instances with custom session name
  axiom-exec whoami -q --cache --sshconfig ~/.axiom/log/exec/axiom-exec+1234567890/sshconfig --fleet oldfleet --tmux # Specify the axiom SSH config to use (default is ~/.axiom/.sshconfig)

---

ax ssh

axiom-images

Manage images/snapshots with axiom-images 💿

axiom-images usage

Examples: axiom-images ls && axiom-images rm axiom-barebones-1634682130 && axiom-images use axiom-default-1634682131
Usage:
ls                                      List snapshots created
get                       Display info about the current image
use | set              Use snapshot for axiom-init/axiom-fleet
rm                                Remove snapshot from account
help | --help | -h                        Print this help menu

axiom-images ls # List available images
axiom-images use <image name> # Replace image used for axiom-init/axiom-fleet with user provided image name 
axiom-images rm <image name> # Delete image by name

---

axiom-init

Initialize a single instance 🌱

axiom-init usage

Description:
Initialize one axiom instance with differnet options, such as image, region, size and axiom deployment profile
Examples:
axiom-init # provision instance with random name
axiom-init --deploy desktop # provision instance with random name, then deploy axiom profile 'desktop'
axiom-init testy01 # provision instance named testy01
axiom-init stok01 --region nyc3 --image axiom-barebones-1635920849 --size s-1vcpu-2gb --deploy desktop --shell
Usage:
<name> string (optional)
  Name of the instance, supplied as a positional first argument
--image <image name>
  Manually set the image to use (default is imageid in ~/.axiom/axiom.json)
--region <region>
  User specified region to use (default is region in ~/.axiom/axiom.json)
--deploy <profile>
  Deploy a profile after initialization (e.g desktop, openvpn, bbrf, wireguard)
--shell (optional)
  Connect to instance after initialization
--size <vm size>
  VM size to use  (default is size in ~/.axiom/account/account.json)
--no-select (optional)
  Dont select instance after initialization (default is to select instance)
--domain <example.com>
  Manually specify the domain to use (default is specified by cloud provider)
--restore <backup>
  Initialize with a previous backup
--help
  Display this help menu

axiom-init <name> # Init
axiom-init <name> --deploy <profile> --restore <box> # Init & deploy & restore 
#Note: profile argument is file name is without .json

the --deploy option allows you to deploy a profile (stored in ~/.axiom/profiles/). --restore will restore a profile. These options can be used together.

axiom-init

You can run this command without any parameters, and it will pick a name for you. This name is picked at random from a list of legends!

# axiom-init <instance name>
axiom-init jerry

If you supply an argument, it will be used as the instance name, in the above example we spin up an instance called "jerry".

axiom-ls

Now you have spun up an instance, you can run axiom-ls and get a list of all running instances.

List your instances - axiom-ls

---

axiom-exec

Execute a command against an Instance 🤖

axiom-exec usage

Description:
Evaluate shell one-liners or execute single commands on one or more instances in parallel                                                                                                                       
Expand local and remote environment variables respectively                                                                                                                                                      
Specify the fleet prefix, or let axiom use selected.conf by default (located in ~/.axiom/selected.conf)                                                                                                         
Optionally execute command(s) in a detached tmux session on the remote instances (commands run in the background)                                                                                               
Temporarily prevent axiom's SSH key regeneration and instead connect with a cached SSH config (default is ~/.axiom/.sshconfig)                                                                                  
Examples:                                                                                                                                                                                                         
axiom-exec id # Execute command id across all instances currently selected.conf (located in ~/.axiom/selected.conf)
axiom-exec ifconfig --fleet testy # Execute ifconfig on testy fleet. Automatically select all instances in fleet testy
axiom-exec sleep "$(($RANDOM % 10))" "&& id &&" echo $HOSTNAME --fleet stok # Evaluate complex one-liners on fleet stok
axiom-exec 'sudo apt dist-upgrade -y' -q --cache --fleet OtherFleet --tmux MySession01 # Quietly execute command(s) inside a detacted tmux session on the remote instances with custom session name
axiom-exec whoami -q --cache --sshconfig ~/.axiom/log/exec/axiom-exec+1234567890/sshconfig --fleet oldfleet --tmux # Specify the axiom SSH config to use (default is ~/.axiom/.sshconfig)
Usage:
<commands> required string
  Command(s) to run on the remote axiom instances, multiple commands can be wrapped in single or double quotes, but not required
-f/--fleet <fleet prefix>
  Fleet prefix to execute on (default is ~/.axiom/selected.conf). Automatic wildcard support
-i/--instance <instance name>
  Single instance to execute on
--tmux <optional tmux session name>
  Execute commands in a detacted tmux session (commands run in the background). The default tmux session name is axiom-exec+$TIMESTAMP, or supply a custom tmux session name
--sshconfig <sshconfig_file> (optional string)
  Path to axiom's SSH config (default is ~/.axiom/.sshconfig)
-q/--quiet
  Disable progress bar, and reduce verbosity
--debug
  Enable debug mode (VERY VERBOSE!)
--cache
  Temporarily do not generate SSH config and instead connect with cached SSH config
--logs
  Do not delete logs (logs will be stored in ~/.axiom/logs/exec/axiom-exec$TIMESTAMP)
--help
  Display this help menu

  axiom-exec id # Execute command id across all instances currently selected.conf (located in ~/.axiom/selected.conf)
  axiom-exec ifconfig --fleet testy # Execute ifconfig on testy fleet. Automatically select all instances in fleet testy
  axiom-exec sleep "$(($RANDOM % 10))" "&& id &&" echo $HOSTNAME --fleet stok # Evaluate complex one-liners on fleet stok
  axiom-exec 'sudo apt dist-upgrade -y' -q --cache --fleet OtherFleet --tmux MySession01 # Quietly execute command(s) inside a detacted tmux session on the remote instances with custom session name
  axiom-exec whoami -q --cache --sshconfig ~/.axiom/log/exec/axiom-exec+1234567890/sshconfig --fleet oldfleet --tmux # Specify the axiom SSH config to use (default is ~/.axiom/.sshconfig)

axiom-ssh

Connect to an instance - axiom-ssh 🔗

axiom-ssh usage

Description:
axiom-ssh dynamically generates axiom's SSH config based on your cloud inventory.
axiom-ssh allows you to connect to your axiom instances over their public or private network interface.
axiom-ssh can drop you right into a freshly created tmux session on the remote instance, and can be used to
attach to a preexisting tmux session.
All additional SSH args are passed to SSH.
Examples:
axiom-ssh testy01 # SSH into instance testy01
axiom-ssh testy01 --tmux mysession1 # SSH into instance testy01 and spawn or attach to session named mysession1
axiom-ssh --just-generate # Always populate axiom's ssh config (located in ~/.axiom/.sshconfig) with public Ip details
axiom-ssh --just-generate private # Always populate axiom's ssh config (located in ~/.axiom/.sshconfig) with private Ip details
axiom-ssh --just-generate cache # Never regenerate axiom's ssh config
axiom-ssh testy01 -L 8080:127.0.0.1:8080 -D 4040  # Port-forward 8080 to local port 8080 and dynamically port foward port 4040 to testy01
Usage:
<instance name> required string
  Instance name supplied as a positional first argument
--mosh/-m <instance name> (optional)
  Connect with mosh
--just_generate <public, private, cache> (optional)
  Specify when to generate the SSH config file and what IPs to use. Options are public, private, cache ( default is public )
--tmux <tmux session name to create>
  Connect to your instance and start new tmux session. If you dont include a session name one will be chosen automatically for you
--tmux-attach/-t <tmux session> (optional)
  Connect to your instance and attach to tmux session by name
--cache (optional)
  Temporarily do not generate SSH config and instead connect with cached SSH config
--help (optional)
  Display this help menu
<additional args>
  All additional SSH args are passed to SSH. If you want additional arguments supplied to your command, simply append them to the command
  example: axiom-ssh <name> -L 8080:127.0.0.1:8080 -D 4040

axiom-connect #automatically connects to list initialized instance
axiom-connect <name>
axiom-ssh <name> <ssh args>
axiom-ssh <name> --tmux
axiom-ssh <name> -m -t <tmux session> # Connect with mosh and attach to tmux session
axiom-ssh <name> -m -t main-15
axiom-ssh <name> -L 8080:127.0.0.1:8080 -D 4040 # All additional SSH args are passed to SSH
axiom-ssh <name> --cache # Don't generate ssh config, just connect with cache
axiom-ssh --just-generate # Generate an SSH config at ~/.axiom/.sshconfig

---

Connect to your instance - axiom-ssh <instance>

Now you have an instance, and it has a public IP address, you can connect to your new instance using axiom-ssh

# axiom-ssh <instance>
axiom-ssh jerry

If you want to be dropped into a tmux session, that will remain after you disconnect, use the --tmux flag.

axiom-ssh jerry --tmux

To detach from this tmux session, run ctrl+a d, this will disconnect you from the box but leave your tmux session running (and any command running in that session!)

---

axiom-backup

Backup an initialized instance to the cloud 🧳

axiom-backup 

After running axiom-init you can set up config files, unique wordlists, private tools etc, take a snapshot of that image and use it to deploy future axiom instances/fleets.

---

Backup an Initialized Instance - axiom-backup <instance>

After running axiom-init you can set up config files, unique wordlists, private tools etc, take a snapshot of that image and use it to deploy future axiom instances/fleets.

axiom-backup jerry

---

axiom-rm

Remove one or more axiom instances ❌

axiom-rm <name> # Delete box by specifying the name
axiom-rm <name> -f # Forcibly delete box by specifying the
axiom-rm <name>\* # Delete all instances that start with <name>. You must escape the asterisk.  
axiom-rm <name>\* -f # Forcibly delete all instances that start with <name>. You must escape the asterisk.  
axiom-rm '\*' # Delete all instances on the account. Must be wrapped in single quote and escape the asterisk. 
axiom-rm '\*' -f # Forcibly delete all instances on the account. Must be wrapped in single quote and escape the asterisk. 

---

Delete your instance

Once you're done with your instance, delete it using the command, axiom-rm <instance>

axiom-rm jerry

# or 

axiom-rm jerry -f

The -f flag will not prompt on deletion, I generally use this, but if you want to be ultra sure omit the -f flag.

More Info

In Summary, a few useful commands to get you up and running, to use basic instances, and interact with them. Please refer to Filesystem Utilities for more details.