{section: Using HTCondor Annex for the First Time}

We assume you already have an AWS account, as well as a log-in account on a Linux machine with a public IP address and an administrator who's willing to open a port for you.  If so, you can follow the instructions for {wiki: UsingCondorAnnexForTheFirstTimeEightSevenZero using HTCondor Annex for the First Time}.

{section: What You'll Need to Know}

To create a HTCondor annex with on-demand instances, you'll need to know two things:

1: A name for it.  "MyFirstAnnex" is a fine name for your first annex.
1: How many instances you want.  For your first annex, when you're checking to make sure things work, you may only want one instance.

{section: Start an Annex}

Entering the following will start an annex named "MyFirstAnnex" with one instance.

{term}
$ condor_annex -count 1 -annex-name MyFirstAnnex
Will request 1 m4.large on-demand instance for 0.83 hours.  Each instance will terminate after being idle for 0.25 hours.
To change the instance type, use the -aws-on-demand-instance-type flag.
To change the lease duration, use the -duration flag.
To change how long an idle instance will wait before terminating itself, use the -idle flag.
Test-Annex-ODI-041c0538be-14b6-40ce-83d8-47a8ac696639
{endterm}

The last line of output can be used to identify annex instances; you won't have to do that unless something goes wrong.

{subsection: instance types}

Each {link: https://aws.amazon.com/ec2/instance-types/ instance type} provides a different number (and/or type) of CPU cores, amount of RAM, local storage, and the like.  If you're not sure, we recommend starting with 'm4.large', which has 2 CPU cores and 8 GiB of RAM.  As noted in the example output above, you can specify an instance type with the =-aws-on-demand-instance-type= flag.

{subsection: leases}

By default, =condor_annex= arranges for your annex's instances to be terminated after =0.83= hours (50 minutes) have passed.  Once it's in place, this lease doesn't depend on your machine, but it's only checked every five minutes, so give your deadlines a lot of cushion to make you don't get charged for an extra hour.  The lease is intended to help you conserve money by preventing the annex instances from accidentally running forever.  As noted in the example output above, you can specify a lease duration (in decimal hours) with the =-duration= flag.

{subsection: idle time}

By default, =condor_annex= will configure your annex's instances to terminate themselves after being idle for =0.25= hours (fifteen minutes).  This is intended to help you conserve money in case of problems or an extended shortage of work.  As noted in the example output above, you can specify a max idle time (in decimal hours) with the =-idle= flag.  =condor_annex= considers an instance idle if it's {link: http://research.cs.wisc.edu/htcondor/manual/v8.6/3_7Policy_Configuration.html#37887 unclaimed}, so it won't get tricked by jobs with long quiescent periods.

{section: Monitor your Annex}

You can find out if that instance has successfully joined the pool in the following way.

{term}
$ condor_status -annex MyFirstAnnex
slot1@ip-172-31-48-84.ec2.internal  LINUX     X86_64 Unclaimed Idle 0.640 3767
slot2@ip-172-31-48-84.ec2.internal  LINUX     X86_64 Unclaimed Idle 0.640 3767

              Total Owner Claimed Unclaimed Matched Preempting Backfill  Drain
 X86_64/LINUX     2     0       0         2       0          0        0      0
        Total     2     0       0         2       0          0        0      0
{endterm}

This example shows that the annex instance you requested has joined your pool.  (The default annex image configures one static slot for each CPU it finds on start-up.)

{section: Stop an Annex}

The following command shuts HTCondor off on each instance in the annex; if you're using the default annex image, doing so causes each instance to shut itself down.

{term}
$ condor_off -master -annex MyFirstAnnex
Sent "Kill-Daemon" command for "master" to master ip-172-31-48-84.ec2.internal
{endterm}

{section: Advanced Usage}

The information is this section is for advanced users and may not apply (or make sense) to everyone.

{subsection: Configure the Annex}

You can customize the configuration of your annex.  If you pass the full path to a directory (for example, =/home/annex/config.d=) to =condor_annex= using the =-config-dir= option, condor_annex will copy the files in that directory to the HTCondor config directory on each annex instance.  This does _not_ replace the customization that =condor_annex= is already doing to configure security and tell the annex instances which pool to join; those changes will be laid down on top of (a temporary copy of) the directory you specified before being transferred to the instances.