Cloud Annex Configuration
=========================

While the configuration macros in this section may be set by the
HTCondor administrator, they are intended for the user-specific HTCondor
configuration file (usually ``~/.condor/user_config``). Although we
document every macro, we expect that users will generally only want to
change a few of them, listed in the
:ref:`cloud-computing/annex-configuration:user settings` section;
the entries required in by :tool:`htcondor annex` in other sections will be
generated by its setup procedure.

Subsequent sections deal with logging
(:ref:`cloud-computing/annex-configuration:logging`), are for expert users
(:ref:`cloud-computing/annex-configuration:expert settings`), or for HTCondor
developers (:ref:`cloud-computing/annex-configuration:developer settings`).

User Settings
-------------

:macro-def:`ANNEX_DEFAULT_AWS_REGION[ANNEX]`
    The default region when using AWS. Defaults to 'us-east-1'.

:macro-def:`ANNEX_DEFAULT_LEASE_DURATION[ANNEX]`
    The duration of an annex if not specified on the command-line;
    specified in seconds. Defaults to 50 minutes.

:macro-def:`ANNEX_DEFAULT_UNCLAIMED_TIMEOUT[ANNEX]`
    How long an annex instances should stay idle before shutting down;
    specified in seconds. Defaults to 15 minutes.

:macro-def:`ANNEX_DEFAULT_ODI_KEY_NAME[ANNEX]`
    The name of the SSH key pair :tool:`htcondor annex` should use by default.
    No default.

:macro-def:`ANNEX_DEFAULT_ODI_INSTANCE_TYPE[ANNEX]`
    The AWS instance type to use for on-demand instances if not
    specified. No default, but the :tool:`htcondor annex` setup procedure sets
    this to 'm4.large'.

:macro-def:`ANNEX_DEFAULT_ODI_IMAGE_ID[ANNEX]`
    The AWS AMI to use for on-demand instance if not specified. No
    default, but the :tool:`htcondor annex` setup procedure sets this to
    'ami-35b13223'.

:macro-def:`ANNEX_DEFAULT_SFR_CONFIG_FILE[ANNEX]`
    The JSON configuration file use by :tool:`htcondor annex` when creating a
    Spot-based annex. No default.

Logging
-------

By default, running :tool:`htcondor annex` creates three logs: the
:tool:`htcondor annex` log, the annex GAHP log, and the annex audit log. The
default location for these logs is the same directory as the
user-specific HTCondor configuration file (usually
~/.condor/user_config). :tool:`htcondor annex` sets the :macro:`LOG`
:index:`LOG` macro to this directory when reading its
configuration.

The :tool:`htcondor annex` log is a daemon-style log. It is configured as if
:tool:`htcondor annex` were a daemon with subsystem type ``ANNEX``; see
:ref:`admin-manual/configuration-macros:daemon logging configuration file
entries` for details.

:tool:`htcondor annex` uses special helper programs, called GAHPs, to interact
with the different cloud services. These programs do their own logging,
writing to the annex GAHP log. The annex GAHP log is configured as if it
were a daemon, but with subsystem type ``ANNEX_GAHP``; see
:ref:`admin-manual/configuration-macros:daemon logging configuration file
entries` for details.

The annex audit log records two lines for each invocation of
:tool:`htcondor annex`: the command as issued and the results as returned. The
location of the audit log is set by
:macro-def:`ANNEX_AUDIT_LOG[ANNEX]`, which is the ``AUDIT``-level log for the
``ANNEX`` subsystem; see :macro:`<SUBSYS>_<LEVEL>_LOG` (in
:ref:`admin-manual/configuration-macros:daemon logging configuration file
entries`) for details. Because annex creation commands typically make extensive
use of values set in configuration, :tool:`htcondor annex` will write the configuration
it used for annex creation commands into the audit log if ``ANNEX_DEBUG``
includes ``D_AUDIT:2``.

Expert Settings
---------------

:macro-def:`ANNEX_DEFAULT_EC2_URL[ANNEX]`
    The AWS EC2 endpoint that :tool:`htcondor annex` should use. Defaults to
    'https://ec2.us-east-1.amazonaws.com'.

:macro-def:`ANNEX_DEFAULT_CWE_URL[ANNEX]`
    The AWS CloudWatch Events endpoint that :tool:`htcondor annex` should use.
    Defaults to 'https://events.us-east-1.amazonaws.com'.

:macro-def:`ANNEX_DEFAULT_LAMBDA_URL[ANNEX]`
    The AWS Lambda endpoint that :tool:`htcondor annex` should use. Defaults to
    'https://lambda.us-east-1.amazonaws.com'.

:macro-def:`ANNEX_DEFAULT_S3_URL[ANNEX]`
    The AWS S3 endpoint that :tool:`htcondor annex` should use. Defaults to
    'https://s3.amazonaws.com'.

:macro-def:`ANNEX_DEFAULT_CF_URL[ANNEX]`
    The AWS CloudFormation endpoint that :tool:`htcondor annex` should use.
    Defaults to 'https://cloudformation.us-east-1.amazonaws.com'.

:macro-def:`ANNEX_DEFAULT_ACCESS_KEY_FILE[ANNEX]`
    The full path to the AWS access key file :tool:`htcondor annex` should use.
    No default. If "FROM INSTANCE", :tool:`htcondor annex` will assume it's
    running on an EC2 instance and try to use that instance's
    credentials.

:macro-def:`ANNEX_DEFAULT_SECRET_KEY_FILE[ANNEX]`
    The full path to the AWS secret key file :tool:`htcondor annex` should use.
    No default. If "FROM INSTANCE", :tool:`htcondor annex` will assume it's
    running on an EC2 instance and try to use that instance's
    credentials.

:macro-def:`ANNEX_DEFAULT_S3_BUCKET[ANNEX]`
    A private S3 bucket that the ``ANNEX_DEFAULT_ACCESS_KEY_FILE`` and
    ``ANNEX_DEFAULT_SECRET_KEY_FILE`` may write to. No default.

:macro-def:`ANNEX_DEFAULT_ODI_SECURITY_GROUP_IDS[ANNEX]`
    The default security group for on-demand annexes. Must permit
    inbound HTCondor (port 9618).

Developer Settings
------------------

:macro-def:`ANNEX_DEFAULT_CONNECTIVITY_FUNCTION_ARN[ANNEX]`
    The name (or ARN) of the Lambda function on AWS which
    :tool:`htcondor annex` should use to check if the configured collector can
    be contacted from AWS.

:macro-def:`ANNEX_DEFAULT_ODI_INSTANCE_PROFILE_ARN[ANNEX]`
    The ARN of the instance profile :tool:`htcondor annex` should use. No
    default.

:macro-def:`ANNEX_DEFAULT_ODI_LEASE_FUNCTION_ARN[ANNEX]`
    The Lambda function which implements the lease (duration) for
    on-demand instances. No default.

:macro-def:`ANNEX_DEFAULT_SFR_LEASE_FUNCTION_ARN[ANNEX]`
    The Lambda function which implements the lease (duration) for Spot
    instances. No default.
