If you're installing Arq on many computers, you can automate the process using an "answer file". The answer file contains all the configuration Arq needs to configure itself, launch Arq Agent, and start backing up.
To better control access to the S3 account on multiple computers, use Amazon IAM (Identity and Access Management) users instead of the S3 account's key pair (see below).
To configure Arq using an answer file, launch the Arq binary within the Arq.app bundle from the command-line as follows:
Arq.app/Contents/MacOS/Arq configure answers.plist
The file answers.plist
must be in the format described in the next section.
The following is a sample answer file. Each section is explained in detail below.
<plist version="1.0"> <dict> <key>appBundlePath</key> <string>/Applications/Arq.app</string> <key>s3BucketName</key> <string>mybucket.comhaystacksoftwarearq</string> <key>s3AccessKey</key> <string>AKIAIIGF5HKHEGDKKSAQ</string> <key>s3SecretKey</key> <string>K1JrMYjg1i99hw1DrULfTN6P7mE01BQEASNosfM/b6rQf6r/KVSeXPyjs8XTnh6N</string> <key>s3SecretKeyIsEncrypted</key> <true></true> <key>computerUUID</key> <string>4499C5C1-957E-407B-9C3E-526F68E0E680</string> <key>encryptionPassword</key> <string>bXk/lMLCcw9uuVXAONLcyw==</string> <key>encryptionPasswordIsEncrypted</key> <true></true> <key>budgetDollars</key> <real>100.0</real> <key>logLevel</key> <string>warn</string> <key>budgetEnforcementIntervalHours</key> <real>96.0</real> <key>throttleType</key> <string>auto</string> <key>throttleKBPS</key> <integer>0</integer> <key>useAmazonRRS</key> <false></false> <key>showHiddenFilesInFileSelectionDialog</key> <false></false> <key>growlOnSuccessfulBackup</key> <false></false> <key>licenseUser</key> <string>Stefan Reitshamer</string> <key>licenseKey</key> <string>(license key)</string> <key>statusItemVisible</key> <true></true> <key>scheduleType</key> <string>hourly</string> <key>minutesAfterHour</key> <integer>0</integer> <key>agentChecksForAppUpdates</key> <false></false> <key>preventSleepDuringBackup</key> <true></true> <key>backupFolders</key> <array> <dict> <key>path</key> <string>/Users/stefan</string> <key>mountPoint</key> <string>/</string> <key>ignoredRelativePaths</key> <array> <string>/Desktop</string> </array> <key>excludes</key> <array> <dict> <key>type</key> <string>regex</string> <key>text</key> <string>^\.</string> </dict> <dict> <key>type</key> <string>endswith</string> <key>text</key> <string>.tmp</string> </dict> </array> </dict> <dict> <key>path</key> <string>/Users/stefan/Library</string> <key>mountPoint</key> <string>/</string> <key>ignoredRelativePaths</key> <array> <string>/Application Support/Developer</string> <string>/Application Support/MobileSync/Backup</string> <string>/Application Support/SyncPhotos</string> <string>/Application Support/SyncServices</string> <string>/Caches</string> <string>/Developer/Xcode/DerivedData</string> <string>/iTunes/iPad Software Updates</string> <string>/iTunes/iPhone Software Updates</string> <string>/iTunes/iPod Software Updates</string> <string>/iTunes/Mobile Backups</string> <string>/Logs</string> <string>/PubSub</string> <string>/Safari/WebpageIcons.db</string> </array> <key>excludes</key> <array> <dict> <key>type</key> <string>equals</string> <key>text</key> <string>.DS_Store</string> </dict> </array> </dict> </array> </dict> </plist>
<key>appBundlePath</key> <string>/Applications/Arq.app</string>
This is the location of the Arq app bundle.
<key>s3BucketName</key> <string>mybucket.comhaystacksoftwarearq</string>
This is the name of the S3 bucket to use (or create if it doesn't exist). This bucket name must have one of the following suffixes:
Arq will use the suffix to figure out which region to create the S3 bucket in.
<key>s3AccessKey</key> <string>AKIAIIGF5HKHEGDKKSAQ</string>
This is the S3 access key ID for your S3 account or IAM user. You may wish to create an IAM account for each computer with a policy to prevent the user of that computer from seeing other computer's backups in the same S3 account. See below for more details on IAM.
<key>s3SecretKey</key> <string>K1JrMYjg1i99hw1DrULfTN6P7mE01BQEASNosfM/b6rQf6r/KVSeXPyjs8XTnh6N</string>
This is the secret access key corresponding to the access key ID above.
<key>s3SecretKeyIsEncrypted</key> <true></true>
This indicates whether the secret access key is encrypted or not. See Encryption below for details on encrypting keys.
<key>computerUUID</key> <string>4499C5C1-957E-407B-9C3E-526F68E0E680</string>
This is a unique ID for the computer's backup data. If you don't supply one, Arq will generate one.
<key>encryptionPassword</key> <string>bXk/lMLCcw9uuVXAONLcyw==</string>
This is the password that Arq uses to encrypt the backup data.
<key>encryptionPasswordIsEncrypted</key> <true></true>
This indicates whether the encryption password is itself encrypted. See Encryption below for details on encrypting keys.
<key>budgetDollars</key> <real>100.0</real>
Arq tries to keep the total size of the backups for this computer below this number. It drops the oldest backup versions (S3 folders only) during the "budget enforcement" process which happens periodically (see 'budgetEnforcementIntervalHours' below). Arq always keeps the latest backup version, even if that means it's over budget.
<key>logLevel</key> <string>warn</string>
This controls the logging level. Valid values are none
, warn
, info
, detail
, debug
, and trace
.
<key>budgetEnforcementIntervalHours</key> <real>96.0</real>
This controls how often Arq performs "budget enforcement", during which it drops oldest backup versions (S3 folders only) to stay under the budget chosen (see 'budgetGB' above). Arq does not perform "budget enforcement" unless it has successfully completed backups of all folders.
<key>throttleType</key> <string>fixed</string> <key>throttleKBPS</key> <integer>50</integer>
This controls Arq's upload rate. Valid values for throttleType
are none
, auto
, and fixed
. If fixed
is chosen, throttleKBPS
must also be specified.
<key>useAmazonRRS</key> <false></false>
This controls whether Arq stores objects in S3 using the "standard" storage class or the "reduced redunancy" storage class. We recommend "standard".
<key>showHiddenFilesInFileSelectionDialog</key> <false></false>
This controls whether hidden files are shown when the user chooses files/folders to add to the backups.
<key>growlOnSuccessfulBackup</key> <false></false>
This controls whether Arq shows a Growl notification upon successful completion of a backup. (Arq always shows a Growl notification when there's an error.)
<key>licenseUser</key> <string>Stefan Reitshamer</string>
This is the value of the name
field in your .arqLicense file. To purchase an Arq license, visit the Haystack Software store.
<key>licenseKey</key> <string>(license key)</string>
This is the value of the licenseKey
field in your .arqLicense file. To purchase an Arq license, visit the Haystack Software store.
<key>statusItemVisible</key> <true></true>
This controls whether the Arq icon appears in the menu bar.
<key>scheduleType</key> <string>daily</string> <key>backupHour</key> <string>2</string>
This controls how often Arq backs up. Valid values for scheduleType
are hourly
and daily
. If daily
is chosen, you must also specify the hour of the day to back up in backupHour
.
<key>minutesAfterHour</key> <integer>0</integer>
This specifies how many minutes after the chosen backup hour to wait before starting backup. This is useful for reducing network contention if you have many computers with hourly Arq backups on the same network.
<key>agentChecksForAppUpdates</key> <false></false>
This controls whether Arq Agent checks for app updates and notifies the user.
<key>preventSleepDuringBackup</key> <true></true>
This controls whether Arq Agent prevents the computer from going to sleep while a backup is in process. It does not prevent computer sleep if the user closes the lid on a laptop.
<key>backupFolders</key> <array> <dict> ... </dict> <dict> ... </dict> ... </array>
This contains an array
of dict
structures describing the folders to back up. Each dict
structure must contain:
<key>path</key> <string>/Users/stefan</string>
df -k <path>
to get the mount point):<key>mountPoint</key> <string>/</string>
<key>ignoredRelativePaths</key> <array> <string>/Desktop</string> </array>
<key>excludes</key> <array> <dict> <key>type</key> <string>regex</string> <key>text</key> <string>^\.</string> </dict> <dict> <key>type</key> <string>endswith</string> <key>text</key> <string>.tmp</string> </dict> </array>
Each exclude within a folder has a type
and a text
. The type must be one of equals
, contains
, startswith
, endswith
, or regex
. For regex
, the text
must be a regular expression in ICU syntax that matches the entire path to the file (not just the filename). For all other types, the text
is a filename or fragment of a filename.
To avoid storing the S3 secret key and/or the encryption password in plain text in the answer file, use Arq to encrypt the value and set the values appropriately in the answer file. For example, to encrypt the S3 secret key:
/Applications/Arq.app/Contents/MacOS/Arq encryptArq will prompt you to enter the value and then enter a "passphrase". It will emit an encrypted value.
s3SecretKeyIsEncrypted
value to true
:<key>s3SecretKey</key> <string>CAJJOnS/+btABsBcwK+QrEMDlRRkspBbMGBGqdK1yQIX861CGXAeocQGXII3wAf3</string> <key>s3SecretKeyIsEncrypted</key> <true></true>
Amazon's IAM (Identity and Access Management) allows you to create users within your AWS account, generate S3 key pairs for them, and assign policies to them.
If you configure Arq to use an IAM user, use the IAM user's access key ID and secret access key in the s3AccessKey
and s3SecretKey
fields of the answer file.
Next, create a policy for that IAM user that allows creating a lifecycle configuration on the S3 bucket, full access to the user's objects and ListBucket permission to the bucket for the user's objects, access to Glacier vaults that start with "arq_", and permission to create SNS topics and SQS queues for use in restoring from legacy (Arq3-created) Glacier backups. For example, if your answer file has a computerUUID
of 32D9D7A2-3B3E-4BE7-B85B-0605AF24F570
and an s3BucketName
of akiaiyuk3n3tme6l4hfa.com.haystacksoftware.arq
, the policy for the user should look like this:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetLifecycleConfiguration", "s3:PutLifecycleConfiguration" ], "Resource": [ "arn:aws:s3:::akiaiyuk3n3tme6l4hfa.com.haystacksoftware.arq" ] } , { "Effect": "Allow", "Action": [ "s3:*" ], "Resource": ["arn:aws:s3:::akiaiyuk3n3tme6l4hfa.com.haystacksoftware.arq/32D9D7A2-3B3E-4BE7-B85B-0605AF24F570/*","arn:aws:s3:::akiaiyuk3n3tme6l4hfa.com.haystacksoftware.arq/glacier/32D9D7A2-3B3E-4BE7-B85B-0605AF24F570/*"] } , { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Condition": { "StringLike": { "s3:prefix": "32D9D7A2-3B3E-4BE7-B85B-0605AF24F570/*" } }, "Resource": [ "arn:aws:s3:::akiaiyuk3n3tme6l4hfa.com.haystacksoftware.arq" ] } , { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Condition": { "StringLike": { "s3:prefix": "glacier/32D9D7A2-3B3E-4BE7-B85B-0605AF24F570/*" } }, "Resource": [ "arn:aws:s3:::akiaiyuk3n3tme6l4hfa.com.haystacksoftware.arq" ] } , { "Effect": "Allow", "Action": [ "glacier:*" ], "Resource": [ "arn:aws:glacier:us-east-1:*:vaults/arq_*" ] } , { "Effect": "Allow", "Action": [ "sns:CreateTopic", "sns:DeleteTopic", "sns:ListTopics", "sns:Subscribe" ], "Resource": [ "arn:aws:sns:us-east-1:*" ] } , { "Effect": "Allow", "Action": [ "sqs:CreateQueue", "sqs:DeleteMessage", "sqs:DeleteQueue", "sqs:GetQueueAttributes", "sqs:ListQueues", "sqs:ReceiveMessage", "sqs:SetQueueAttributes" ], "Resource": [ "arn:aws:sqs:us-east-1:*" ] } ] }
The above policy allows Arq on that computer to see only its own backup data.
To automatically generate a policy, configure Arq with an admin IAM user and then double-click the target in the preferences and click the "Create Restricted IAM User" button.