# 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`](https://github.com/pry0cc/axiom/wiki/A-Quickstart-Guide#axiom-configure) script at some point. axiom-configure automatically starts [`axiom-build`](https://github.com/pry0cc/axiom/wiki/A-Quickstart-Guide#axiom-build). During this time, [Packer by HashiCorp](https://www.packer.io/) 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`](https://github.com/pry0cc/axiom/wiki/A-Quickstart-Guide#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`](https://github.com/pry0cc/axiom/wiki/A-Quickstart-Guide#axiom-init). ## ax configure **Setup and configure the axiom controller and validate cloud account** :computer:
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 # Use personal.json from a file for account setup axiom-configure --config # 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 # 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 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 (optional) Add axiom to path, backup .zshrc/.bashrc to .zshrcbak/.bashrcbak --debug (optional) Enable debug mode (VERY VERBOSE!) --help Display this help menu ```
{% code fullWidth="false" %} ``` ax configure --setup ``` {% endcode %} 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** :hatching\_chick: > You must run axiom-configure before anything else. This creates your axiom.json file which is required by other commands. {% code fullWidth="false" %} ``` 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: (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 (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 ``` {% endcode %} {% code fullWidth="false" %} ``` axiom-build default ``` {% endcode %} 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](https://github.com/attacksurge/ax/blob/master/images/provisioners/default.json) is our latest iteration of axiom provisioners. It comes with many tools installed and has been optimized for readability. Recommended for axiom-fleet. > * [ReconFTW](https://github.com/attacksurge/ax/blob/master/images/provisioners/reconftw.json) provisioner includes all tools in ReconFTW and works with most modules. Recommended for ReconFTW. > * [Barebones](https://github.com/attacksurge/ax/blob/master/images/provisioners/barebones.json) is our decently secure base install, comes with Docker, Go-lang, Interlace and nmap installed. Recommended for templating. > * [Extras](https://github.com/attacksurge/ax/blob/master/images/provisioners/extras.json) has more tools installed than our Default provisioner To use your own Provisioner, read [Bring Your Own Provisioner](https://ax-framework.gitbook.io/wiki/fundamentals/bring-your-own-provisioner). ## ax images **Manage images/snapshots with axiom-images** :cd: {% code fullWidth="true" %} ``` 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 Specify an image by name to delete (must be an image name from 'axiom-images ls') create Kick off axiom-images creation wizard or specify an instance to create an image from 'axiom-images create $instance_name' select 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 ``` {% endcode %} {% code fullWidth="true" %} ```bash axiom-images ls # List available images axiom-images use # Replace image used for axiom-init/axiom-fleet with user provided image name axiom-images rm # 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 ``` {% endcode %} *** ## ax init **Initialize a single instance** :seedling: {% code fullWidth="true" %} ``` 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: string (optional) Name of the instance, supplied as a positional first argument --run (optional) Create one instance with random name --image Manually set the image to use (default is imageid in ~/.axiom/axiom.json) --region User specified region to use (default is region in ~/.axiom/axiom.json) --deploy Deploy a profile after initialization (e.g desktop, openvpn, bbrf, wireguard) --shell (optional) Connect to instance after initialization --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 ``` {% endcode %} {% code fullWidth="true" %} ```bash ax init # Init ax init --run # Init with random instance name ax init --deploy=# Init and install deployment profile ``` {% endcode %} > the `--deploy` option allows you to install a deployment profile (stored in `~/.axiom/profiles/`) *** ## ax exec **Execute a command against one or many instances** :robot: {% code fullWidth="true" %} ``` 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: 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 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 Single instance to execute on --sshconfig (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 Specifies the timeout (in seconds) used when connecting to the SSH server, instead of using the default 5 seconds --help Display this help menu ``` {% endcode %} {% code fullWidth="true" %} ```bash 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) ``` {% endcode %} *** ## ax ssh ## axiom-images **Manage images/snapshots with axiom-images** :cd: ##
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 ```
```bash axiom-images ls # List available images axiom-images use # Replace image used for axiom-init/axiom-fleet with user provided image name axiom-images rm # Delete image by name ``` *** ## axiom-init **Initialize a single instance** :seedling: ##
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: string (optional) Name of the instance, supplied as a positional first argument --image Manually set the image to use (default is imageid in ~/.axiom/axiom.json) --region User specified region to use (default is region in ~/.axiom/axiom.json) --deploy Deploy a profile after initialization (e.g desktop, openvpn, bbrf, wireguard) --shell (optional) Connect to instance after initialization --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 Manually specify the domain to use (default is specified by cloud provider) --restore Initialize with a previous backup --help Display this help menu ```
```bash axiom-init # Init axiom-init --deploy --restore # 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 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** :robot: ##
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: 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 to execute on (default is ~/.axiom/selected.conf). Automatic wildcard support -i/--instance Single instance to execute on --tmux 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 (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 ```
```bash 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** :link: ##
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: required string Instance name supplied as a positional first argument --mosh/-m (optional) Connect with mosh --just_generate (optional) Specify when to generate the SSH config file and what IPs to use. Options are public, private, cache ( default is public ) --tmux 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 (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 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 -L 8080:127.0.0.1:8080 -D 4040 ```
```bash axiom-connect #automatically connects to list initialized instance axiom-connect axiom-ssh axiom-ssh --tmux axiom-ssh -m -t # Connect with mosh and attach to tmux session axiom-ssh -m -t main-15 axiom-ssh -L 8080:127.0.0.1:8080 -D 4040 # All additional SSH args are passed to SSH axiom-ssh --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 ` Now you have an instance, and it has a public IP address, you can connect to your new instance using `axiom-ssh` ``` # axiom-ssh 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** :luggage: ```bash 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 ` 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** :x: ```bash axiom-rm # Delete box by specifying the name axiom-rm -f # Forcibly delete box by specifying the axiom-rm \* # Delete all instances that start with . You must escape the asterisk. axiom-rm \* -f # Forcibly delete all instances that start with . 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 ` ``` 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](https://github.com/pry0cc/axiom/wiki/Filesystem-Utilities) for more details. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ax.attacksurge.com/overview/quickstart-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.