Setup

Introduction

This page describes how to set up the armory server. The armory server can be run as a standalone executable or in a Docker container. Details on using the armory Docker container are here.

Initial setup

The armory can be set up via command line arguments, environment variables, or by answering a series of questions. The order of precedence is as follows:

1. Command line arguments
2. Environment variables
3. Configuration file

The server can be started by running it from the command line:

./armory-server

Running the server with the -h option will show the various command line options you can use to configure the server. Even after initial setup, you can run the server with command line options and the values of those options will override whatever is in the configuration file for those options.

When you run the armory executable for the first time, it will ask for any information that is not provided through the command line or environment variables. Therefore, if you would like to set up the armory without user action, then all information should be provided through the command line and/or environment variables. Note that if you are using the local signing key provider, you will be prompted for a password each time the armory starts unless you specify the password through the ARMORY_SIGNING_KEY_PASSWORD environment variable.

The configuration file is saved in <armory-root>/config.json after initial set up is complete. This file can be edited as necessary. Changes do not take effect until the server is restarted.

The configuration file

A sample configuration file is shown below:

{
  "domain_name": "awesomearmory.com",
  "lhost": "",
  "lport": 8888,
  "tls_enabled": true,
  "root_dir": "/data/armory-data",
  "public_key": "RWTek28+XApVLEtNGrW3RIqQbLBFnhSlAsMb2Y6i+JEPytq0aCgIJhTM",
  "authentication_disabled": false,
  "authorization_token_digest": "0c60a93ffebafb2dba1e3f7b04e8ea56b749a222b78ef8a8ea3722177fa017a2",
  "write_timeout": 300000000000,
  "read_timeout": 300000000000,
  "signing_key_provider": "local"
}

After initial setup, this file should not have to be edited often, if at all. The fields in the file are as follows:

Field	Description
domain_name	The hostname or IP that clients will use to connect to the armory. If left blank, the IP of the server is used.
lhost	The interface to listen on. A blank value means all interfaces.
tls_enabled	true if TLS is enabled, false otherwise. Certificates are stored in <armory-root>/certificates/armory.key (private key) and <armory-root>/certificates/armory.crt (certificate).
root_dir	The directory where all armory data is stored, including configuration and hosted packages.
public_key	The public key for package signing.
authentication_disabled	Clients can authenticate to the armory using a token in the Authorization field of the request. This token is the same for all clients. The value of this field is true if client authentication is disabled, false if client authentication is enabled.
authentication_digest	A hash of the authentication token.
read_timeout, write_timeout	A value in nanoseconds for the read and write timeouts, respectively, of requests to the armory. The read timeout is the maximum duration for reading the request, and the write timeout is the maximum duration for writing the response. Both default to 5 minutes.
signing_key_provider	The source of the package signing key. The choices are local, external, aws, and vault. More information about signing providers is here: Package Signing Providers
signing_key_provider_details	If the signing key provider is not local, this map holds the necessary information to retrieve the signing key from the provider. For AWS, the map looks like this: "signing_key_provider_details": { "secret-name": "my-signing-key", "region": "us-west-2" } For Vault, the map looks like this: "signing_key_provider_details": { "addr": "http://my-vault:8200/", "app-role-path": "armory", "key-path": "secrets/armory/signingkey/key", "roleID": "9838aec3-d862-15a2-9818-f81c7b4e956d", "secretID": "3bcd8c7f-591d-a252-6144-4e676d7486c8" }