{{define "main"}}aptly(1) -- {{.Short}}
=============================================

## SYNOPSIS

Common command format:

  `aptly` [<global options>...] <command> <subcommand> [<options>...] <arguments>

aptly has integrated help that matches contents of this manual page, to get help, prepend
`help` to command name:

   `aptly` `help` `mirror` `create`

## DESCRIPTION

{{.Long}}

## CONFIGURATION

aptly looks for configuration file first in `~/.aptly.conf` then
in `/etc/aptly.conf` and, if no config file found, new one is created in
home directory. If `-config=` flag is specified, aptly would use config file at specified
location. Also aptly needs root directory for database, package and published repository storage.
If not specified, directory defaults to `~/.aptly`, it will be created if missing.

Configuration file is stored in JSON format (default values shown below):

    {
      "rootDir": "$HOME/.aptly",
      "downloadConcurrency": 4,
      "downloadSpeedLimit": 0,
      "architectures": [],
      "dependencyFollowSuggests": false,
      "dependencyFollowRecommends": false
      "dependencyFollowAllVariants": false,
      "dependencyFollowSource": false,
      "gpgDisableSign": false,
      "gpgDisableVerify": false,
      "downloadSourcePackages": false,
      "ppaDistributorID": "ubuntu",
      "ppaCodename": "",
      "S3PublishEndpoints": {
        "test": {
          "region": "us-east-1",
          "bucket": "repo",
          "endpoint": "",
          "awsAccessKeyID": "",
          "awsSecretAccessKey": "",
          "prefix": "",
          "acl": "public-read",
          "storageClass": "",
          "encryptionMethod": "",
          "plusWorkaround": false,
          "disableMultiDel": false
        }
      },
      "SwiftPublishEndpoints": {
        "test": {
          "container": "repo",
          "osname": "",
          "password": "",
          "prefix": "",
          "authurl": "",
          "tenant": "",
          "tenantid": ""
        }
      }
    }

Options:

  * `rootDir`:
    is root of directory storage to store database (`rootDir`/db), downloaded packages (`rootDir`/pool) and
    published repositories (`rootDir`/public)

  * `downloadConcurrency`:
    is a number of parallel download threads to use when downloading packages

  * `downloadSpeedLimit`:
    limit in kbytes/sec on download speed while mirroring remote repositieis

  * `architectures`:
    is a list of architectures to process; if left empty defaults to all available architectures; could be
    overridden with option `-architectures`

  * `dependencyFollowSuggests`:
    follow contents of `Suggests:` field when processing dependencies for the package

  * `dependencyFollowRecommends`:
    follow contents of `Recommends:` field when processing dependencies for the package

  * `dependencyFollowAllVariants`:
    when dependency looks like `package-a | package-b`, follow both variants always

  * `dependencyFollowSource`:
    follow dependency from binary package to source package

  * `gpgDisableSign`:
    don't sign published repositories with gpg(1), also can be disabled on
    per-repo basis using `-skip-signing` flag when publishing

  * `gpgDisableVerify`:
    don't verify remote mirrors with gpg(1), also can be disabled on
    per-mirror basis using `-ignore-signatures` flag when creating and updating mirrors

  * `downloadSourcePackages`:
    if enabled, all mirrors created would have flag set to download source packages;
    this setting could be controlled on per-mirror basis with `-with-sources` flag

  * `ppaDistributorID`, `ppaCodename`:
    specifies paramaters for short PPA url expansion, if left blank they default
    to output of `lsb_release` command

  * `S3PublishEndpoints`:
    configuration of Amazon S3 publishing endpoints (see below)

  * `SwiftPublishEndpoints`:
    configuration of OpenStack Swift publishing endpoints (see below)

## S3 PUBLISHING ENDPOINTS

aptly could be configured to publish repository directly to Amazon S3 (or S3-compatible
cloud storage). First, publishing
endpoints should be described in aptly configuration file. Each endpoint has name
and associated settings:

   * `region`:
     Amazon region for S3 bucket (e.g. `us-east-1`)
   * `bucket`:
     bucket name
   * `endpoint`:
     (optional) when using S3-compatible cloud storage, specify hostname of service endpoint here,
     region is ignored if endpoint is set (set region to some human-readable name)
     (should be left blank for real Amazon S3)
   * `prefix`:
     (optional) do publishing under specified prefix in the bucket, defaults to
     no prefix (bucket root)
   * `acl`:
     (optional) assign ACL to published files (one of the canned ACLs in Amazon
     terminology). Useful values: `private` (default) or `public-read` (public
     repository). Public repositories could be consumed by `apt` using
     HTTP endpoint (Amazon bucket should be configured for "website hosting"),
     for private repositories special apt S3 transport is required.
   * `awsAccessKeyID`, `awsSecretAccessKey`:
     (optional) Amazon credentials to access S3 bucket. If not supplied,
     environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
     are used.
   * `storageClass`:
     (optional) Amazon S3 storage class, defaults to `STANDARD`. Other values
     available: `REDUCED_REDUNDANCY` (lower price, lower redundancy)
   * `encryptionMethod`:
     (optional) server-side encryption method, defaults to none. Currently
     the only available encryption method is `AES256`
   * `plusWorkaround`:
     (optional) workaround misbehavior in apt and Amazon S3
     for files with `+` in filename by
     creating two copies of package files with `+` in filename: one original
     and another one with spaces instead of plus signs
     With `plusWorkaround` enabled, package files with plus sign
     would be stored twice. aptly might not cleanup files with spaces when published
     repository is dropped or updated (switched) to new version of repository (snapshot)
   * `disableMultiDel`:
     (optional) for S3-compatible cloud storages which do not support `MultiDel` S3 API,
     enable this setting (file deletion would be slower with this setting enabled)

In order to publish to S3, specify endpoint as `s3:endpoint-name:` before
publishing prefix on the command line, e.g.:

  `aptly publish snapshot wheezy-main s3:test:`

## OPENSTACK SWIFT PUBLISHING ENDPOINTS

aptly could be configured to publish repository directly to OpenStack Swift. First,
publishing endpoints should be described in aptly configuration file. Each endpoint
has name and associated settings:

   * `container`:
     container name
   * `prefix`:
     (optional) do publishing under specified prefix in the container, defaults to
     no prefix (container root)
   * `osname`, `password`:
     (optional) OpenStack credentials to access Keystone. If not supplied,
     environment variables `OS_USERNAME` and `OS_PASSWORD` are used.
   * `tenant`, `tenantid`:
     (optional) OpenStack tenant name and id (in order to use v2 authentication).
   * `authurl`:
     (optional) the full url of Keystone server (including port, and version).
     example `http://identity.example.com:5000/v2.0`

In order to publish to Swift, specify endpoint as `swift:endpoint-name:` before
publishing prefix on the command line, e.g.:

  `aptly publish snapshot jessie-main swift:test:`

## PACKAGE QUERY

Some commands accept package queries to identify list of packages to process.
Package query syntax almost matches `reprepro` query language. Query consists of
the following simple terms:

  * direct package reference:
    reference to exaclty one package. Format is identical to the way aptly lists packages in
    show commands with `-with-packages` flag: `name_version_arch`,
    e.g.: `libmysqlclient18_5.5.35-rel33.0-611.squeeze_amd64`

  * dependency condition:
    syntax follows Debian dependency specification: package_name followed by optional version specification
    and architecture limit, e.g: `mysql-client (>= 3.6)`.

  * query against package fields:
    syntax is the same as for dependency conditions, but instead of package name field name is used, e.g:
    `Priority (optional)`.

Supported fields:

  * all field names from Debian package control files are supported except for `Filename`, `MD5sum`,
    `SHA1`, `SHA256`, `Size`, `Files`, `Checksums-SHA1`, `Checksums-SHA256`.
  * `$Source` is a name of source package (for binary packages)
  * `$SourceVersion` is a version of source package
  * `$Architecture` is `Architecture` for binary packages and `source` for source packages,
     when matching with equal (`=`) operator, package with `any` architecture matches all architectures
     but `source`.
  * `$Version` has the same value as `Version`, but comparison operators use Debian
     version precedence rules
  * `$PackageType` is `deb` for binary packages and `source` for source packages

Operators:

  * `=`:
    strict match, default operator is no operator is given
  * `>=`, `<=`, `=`, `>>` (strictly greater), `<<` (strictly less):
    lexicographical comparison for all fields and special rules when comparing package versions
  * `%`:
    pattern matching, like shell patterns, supported special symbols are: `[^]?*`, e.g.:
    `$Version (% 3.5-*)`
  * `~`:
    regular expression matching, e.g.:
    `Name (~ .*-dev)`

Simple terms could be combined into more complex queries using operators `,` (and), `|` (or) and
`!` (not), parentheses `()` are used to change operator precedence. Match value could be
enclosed in single (`'`) or double (`"`) quotes if required to resolve ambiguity, quotes
inside quoted string should escaped with slash (`\`).

Examples:

  * `mysql-client`:
     matches package mysql-client of any version and architecture (including source), also
     matches packages that `Provide:` `mysql-client`.

  * `mysql-client (>= 3.6)`:
     matches package mysql-client with version greater or equal to 3.6. Valid operators for
     version are: `>=`, `<=`, `=`, `>>` (strictly greater), `<<` (strictly less).

  * `mysql-client {i386}`:
     matches package `mysql-client` on architecture `i386`, architecture `all` matches all architectures but source.

  * `mysql-client (>= 3.6) {i386}`:
    version and architecture conditions combined.

  * `libmysqlclient18_5.5.35-rel33.0-611.squeeze_amd64`:
    direct package reference.

  * `$Source (nginx)`:
    all binary packages with `nginx` as source package.

  * `!Name (~ .*-dev), mail-transport, $Version (>= 3.5)`:
    matches all packages that provide `mail-transport` with name that has no suffix `-dev` and
    with version greater or equal to `3.5`.

When specified on command line, query may have to be quoted according to shell rules, so that it stays single argument:

  `aptly repo import percona stable 'mysql-client (>= 3.6)'`


## GLOBAL OPTIONS

{{template "options" .}}

{{template "command" findCommand . "mirror"}}

{{template "command" findCommand . "repo"}}

{{template "command" findCommand . "snapshot"}}

{{template "command" findCommand . "publish"}}

{{template "command" findCommand . "package"}}

{{template "command" findCommand . "db"}}

{{template "command" findCommand . "serve"}}

{{template "command" findCommand . "api"}}

{{template "command" findCommand . "graph"}}

{{template "command" findCommand . "config"}}

{{template "command" findCommand . "task"}}

{{template "command" findCommand . "config"}}

## ENVIRONMENT

If environment variable `HTTP_PROXY` is set `aptly` would use its value
to proxy all HTTP requests.

## RETURN VALUES

`aptly` exists with:

 * 0:
   success

 * 1:
   general failure

 * 2:
   command parse failure

## AUTHORS

Andrey Smirnov (me@smira.ru)

{{end}}

{{/* command list */}}
{{define "command"}}
{{if .Runnable}}
## {{toUpper .Short}}

{{capitalize .Parent.FullSpacedName}} {{capitalize .UsageLine}}

{{.Long}}

{{if (allFlags .Flag | len) gt 0}}
Options:

{{template "options" .}}
{{end}}

{{end}}

{{range .Subcommands}}{{template "command" .}}{{end}}
{{end}}

{{/* options layout */}}
{{define "options"}}
{{range allFlags .Flag}}
  * -`{{.Name}}`={{.DefValue}}:
    {{.Usage}}
{{end}}
{{end}}