1{{define "main"}}aptly(1) -- {{.Short}}
2=============================================
3
4## SYNOPSIS
5
6Common command format:
7
8  `aptly` [<global options>...] <command> <subcommand> [<options>...] <arguments>
9
10aptly has integrated help that matches contents of this manual page, to get help, prepend
11`help` to command name:
12
13   `aptly` `help` `mirror` `create`
14
15## DESCRIPTION
16
17{{.Long}}
18
19## CONFIGURATION
20
21aptly looks for configuration file first in `~/.aptly.conf` then
22in `/etc/aptly.conf` and, if no config file found, new one is created in
23home directory. If `-config=` flag is specified, aptly would use config file at specified
24location. Also aptly needs root directory for database, package and published repository storage.
25If not specified, directory defaults to `~/.aptly`, it will be created if missing.
26
27Configuration file is stored in JSON format (default values shown below):
28
29    {
30      "rootDir": "$HOME/.aptly",
31      "downloadConcurrency": 4,
32      "downloadSpeedLimit": 0,
33      "architectures": [],
34      "dependencyFollowSuggests": false,
35      "dependencyFollowRecommends": false,
36      "dependencyFollowAllVariants": false,
37      "dependencyFollowSource": false,
38      "dependencyVerboseResolve": false,
39      "gpgDisableSign": false,
40      "gpgDisableVerify": false,
41      "gpgProvider": "gpg",
42      "downloadSourcePackages": false,
43      "skipLegacyPool": true,
44      "ppaDistributorID": "ubuntu",
45      "ppaCodename": "",
46      "skipContentsPublishing": false,
47      "FileSystemPublishEndpoints": {
48        "test1": {
49          "rootDir": "/opt/srv1/aptly_public",
50          "linkMethod": "symlink"
51        },
52        "test2": {
53          "rootDir": "/opt/srv2/aptly_public",
54          "linkMethod": "copy",
55          "verifyMethod": "md5"
56        },
57        "test3": {
58          "rootDir": "/opt/srv3/aptly_public",
59          "linkMethod": "hardlink"
60        }
61      },
62      "S3PublishEndpoints": {
63        "test": {
64          "region": "us-east-1",
65          "bucket": "repo",
66          "endpoint": "",
67          "awsAccessKeyID": "",
68          "awsSecretAccessKey": "",
69          "prefix": "",
70          "acl": "public-read",
71          "storageClass": "",
72          "encryptionMethod": "",
73          "plusWorkaround": false,
74          "disableMultiDel": false,
75          "forceSigV2": false,
76          "debug": false
77        }
78      },
79      "SwiftPublishEndpoints": {
80        "test": {
81          "container": "repo",
82          "osname": "",
83          "password": "",
84          "prefix": "",
85          "authurl": "",
86          "tenant": "",
87          "tenantid": ""
88        }
89      }
90    }
91
92Options:
93
94  * `rootDir`:
95    is root of directory storage to store database (`rootDir`/db), downloaded packages (`rootDir`/pool) and
96    the default for published repositories (`rootDir`/public)
97
98  * `downloadConcurrency`:
99    is a number of parallel download threads to use when downloading packages
100
101  * `downloadSpeedLimit`:
102    limit in kbytes/sec on download speed while mirroring remote repositieis
103
104  * `architectures`:
105    is a list of architectures to process; if left empty defaults to all available architectures; could be
106    overridden with option `-architectures`
107
108  * `dependencyFollowSuggests`:
109    follow contents of `Suggests:` field when processing dependencies for the package
110
111  * `dependencyFollowRecommends`:
112    follow contents of `Recommends:` field when processing dependencies for the package
113
114  * `dependencyFollowAllVariants`:
115    when dependency looks like `package-a | package-b`, follow both variants always
116
117  * `dependencyFollowSource`:
118    follow dependency from binary package to source package
119
120  * `dependencyVerboseResolve`:
121    print additional details while resolving dependencies (useful for debugging)
122
123  * `gpgDisableSign`:
124    don't sign published repositories with gpg(1), also can be disabled on
125    per-repo basis using `-skip-signing` flag when publishing
126
127  * `gpgDisableVerify`:
128    don't verify remote mirrors with gpg(1), also can be disabled on
129    per-mirror basis using `-ignore-signatures` flag when creating and updating mirrors
130
131  * `gpgProvider`:
132    implementation of PGP signing/validation - `gpg` for external `gpg` utility or
133    `internal` to use Go internal implementation; `gpg1` might be used to force use
134    of GnuPG 1.x, `gpg2` enables GnuPG 2.x only; default is to use GnuPG 1.x if
135    available and GnuPG 2.x otherwise
136
137  * `downloadSourcePackages`:
138    if enabled, all mirrors created would have flag set to download source packages;
139    this setting could be controlled on per-mirror basis with `-with-sources` flag
140
141  * `skipLegacyPool`:
142    in aptly up to version 1.0.0, package files were stored in internal package pool
143    with MD5-dervied path, since 1.1.0 package pool layout was changed;
144    if option is enabled, aptly stops checking for legacy paths;
145    by default option is enabled for new aptly installations and disabled when
146    upgrading from older versions
147
148  * `ppaDistributorID`, `ppaCodename`:
149    specifies paramaters for short PPA url expansion, if left blank they default
150    to output of `lsb_release` command
151
152  * `FileSystemPublishEndpoints`:
153    configuration of local filesystem publishing endpoints (see below)
154
155  * `S3PublishEndpoints`:
156    configuration of Amazon S3 publishing endpoints (see below)
157
158  * `SwiftPublishEndpoints`:
159    configuration of OpenStack Swift publishing endpoints (see below)
160
161## FILESYSTEM PUBLISHING ENDPOINTS
162
163aptly defaults to publish to a single publish directory under `rootDir`/public. For
164a more advanced publishing strategy, you can define one or more filesystem endpoints in the
165`FileSystemPublishEndpoints` list of the aptly configuration file. Each endpoint has a name
166and the following associated settings:
167
168   * `rootDir`:
169     The publish directory, e.g., `/opt/srv/aptly_public`.
170   * `linkMethod`:
171     This is one of `hardlink`, `symlink` or `copy`. It specifies how aptly links the
172     files from the internal pool to the published directory.
173     If not specified, empty or wrong, this defaults to `hardlink`.
174   * `verifyMethod`:
175     This is used only when setting the `linkMethod` to `copy`. Possible values are
176     `md5` and `size`. It specifies how aptly compares existing links from the
177     internal pool to the published directory. The `size` method compares only the
178     file sizes, whereas the `md5` method calculates the md5 checksum of the found
179     file and compares it to the desired one.
180     If not specified, empty or wrong, this defaults to `md5`.
181
182In order to publish to such an endpoint, specify the endpoint as `filesystem:endpoint-name`
183with `endpoint-name` as the name given in the aptly configuration file. For example:
184
185  `aptly publish snapshot wheezy-main filesystem:test1:wheezy/daily`
186
187## S3 PUBLISHING ENDPOINTS
188
189aptly could be configured to publish repository directly to Amazon S3 (or S3-compatible
190cloud storage). First, publishing
191endpoints should be described in aptly configuration file. Each endpoint has name
192and associated settings:
193
194   * `region`:
195     Amazon region for S3 bucket (e.g. `us-east-1`)
196   * `bucket`:
197     bucket name
198   * `endpoint`:
199     (optional) when using S3-compatible cloud storage, specify hostname of service endpoint here,
200     region is ignored if endpoint is set (set region to some human-readable name)
201     (should be left blank for real Amazon S3)
202   * `prefix`:
203     (optional) do publishing under specified prefix in the bucket, defaults to
204     no prefix (bucket root)
205   * `acl`:
206     (optional) assign ACL to published files (one of the canned ACLs in Amazon
207     terminology). Useful values: `private` (default) or `public-read` (public
208     repository). Public repositories could be consumed by `apt` using
209     HTTP endpoint (Amazon bucket should be configured for "website hosting"),
210     for private repositories special apt S3 transport is required.
211   * `awsAccessKeyID`, `awsSecretAccessKey`:
212     (optional) Amazon credentials to access S3 bucket. If not supplied,
213     environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
214     are used.
215   * `storageClass`:
216     (optional) Amazon S3 storage class, defaults to `STANDARD`. Other values
217     available: `REDUCED_REDUNDANCY` (lower price, lower redundancy)
218   * `encryptionMethod`:
219     (optional) server-side encryption method, defaults to none. Currently
220     the only available encryption method is `AES256`
221   * `plusWorkaround`:
222     (optional) workaround misbehavior in apt and Amazon S3
223     for files with `+` in filename by
224     creating two copies of package files with `+` in filename: one original
225     and another one with spaces instead of plus signs
226     With `plusWorkaround` enabled, package files with plus sign
227     would be stored twice. aptly might not cleanup files with spaces when published
228     repository is dropped or updated (switched) to new version of repository (snapshot)
229   * `disableMultiDel`:
230     (optional) for S3-compatible cloud storages which do not support `MultiDel` S3 API,
231     enable this setting (file deletion would be slower with this setting enabled)
232   * `forceSigV2`:
233     (optional) disable Signature V4 support, useful with non-AWS S3-compatible object stores
234     which do not support SigV4, shouldn't be enabled for AWS
235   * `debug`:
236     (optional) enables detailed request/response dump for each S3 operation
237
238In order to publish to S3, specify endpoint as `s3:endpoint-name:` before
239publishing prefix on the command line, e.g.:
240
241  `aptly publish snapshot wheezy-main s3:test:`
242
243## OPENSTACK SWIFT PUBLISHING ENDPOINTS
244
245aptly could be configured to publish repository directly to OpenStack Swift. First,
246publishing endpoints should be described in aptly configuration file. Each endpoint
247has name and associated settings:
248
249   * `container`:
250     container name
251   * `prefix`:
252     (optional) do publishing under specified prefix in the container, defaults to
253     no prefix (container root)
254   * `osname`, `password`:
255     (optional) OpenStack credentials to access Keystone. If not supplied,
256     environment variables `OS_USERNAME` and `OS_PASSWORD` are used.
257   * `tenant`, `tenantid`:
258     (optional) OpenStack tenant name and id (in order to use v2 authentication).
259   * `authurl`:
260     (optional) the full url of Keystone server (including port, and version).
261     example `http://identity.example.com:5000/v2.0`
262
263In order to publish to Swift, specify endpoint as `swift:endpoint-name:` before
264publishing prefix on the command line, e.g.:
265
266  `aptly publish snapshot jessie-main swift:test:`
267
268## PACKAGE QUERY
269
270Some commands accept package queries to identify list of packages to process.
271Package query syntax almost matches `reprepro` query language. Query consists of
272the following simple terms:
273
274  * direct package reference:
275    reference to exaclty one package. Format is identical to the way aptly lists packages in
276    show commands with `-with-packages` flag: `name_version_arch`,
277    e.g.: `libmysqlclient18_5.5.35-rel33.0-611.squeeze_amd64`
278
279  * dependency condition:
280    syntax follows Debian dependency specification: package_name followed by optional version specification
281    and architecture limit, e.g: `mysql-client (>= 3.6)`.
282
283  * query against package fields:
284    syntax is the same as for dependency conditions, but instead of package name field name is used, e.g:
285    `Priority (optional)`.
286
287Supported fields:
288
289  * all field names from Debian package control files are supported except for `Filename`, `MD5sum`,
290    `SHA1`, `SHA256`, `Size`, `Files`, `Checksums-SHA1`, `Checksums-SHA256`.
291  * `$Source` is a name of source package (for binary packages)
292  * `$SourceVersion` is a version of source package
293  * `$Architecture` is `Architecture` for binary packages and `source` for source packages,
294     when matching with equal (`=`) operator, package with `any` architecture matches all architectures
295     but `source`.
296  * `$Version` has the same value as `Version`, but comparison operators use Debian
297     version precedence rules
298  * `$PackageType` is `deb` for binary packages and `source` for source packages
299
300Operators:
301
302  * `=`:
303    strict match, default operator is no operator is given
304  * `>=`, `<=`, `=`, `>>` (strictly greater), `<<` (strictly less):
305    lexicographical comparison for all fields and special rules when comparing package versions
306  * `%`:
307    pattern matching, like shell patterns, supported special symbols are: `[^]?*`, e.g.:
308    `$Version (% 3.5-*)`
309  * `~`:
310    regular expression matching, e.g.:
311    `Name (~ .*-dev)`
312
313Simple terms could be combined into more complex queries using operators `,` (and), `|` (or) and
314`!` (not), parentheses `()` are used to change operator precedence. Match value could be
315enclosed in single (`'`) or double (`"`) quotes if required to resolve ambiguity, quotes
316inside quoted string should escaped with slash (`\`).
317
318Examples:
319
320  * `mysql-client`:
321     matches package mysql-client of any version and architecture (including source), also
322     matches packages that `Provide:` `mysql-client`.
323
324  * `mysql-client (>= 3.6)`:
325     matches package mysql-client with version greater or equal to 3.6. Valid operators for
326     version are: `>=`, `<=`, `=`, `>>` (strictly greater), `<<` (strictly less).
327
328  * `mysql-client {i386}`:
329     matches package `mysql-client` on architecture `i386`, architecture `all` matches all architectures but source.
330
331  * `mysql-client (>= 3.6) {i386}`:
332    version and architecture conditions combined.
333
334  * `libmysqlclient18_5.5.35-rel33.0-611.squeeze_amd64`:
335    direct package reference.
336
337  * `$Source (nginx)`:
338    all binary packages with `nginx` as source package.
339
340  * `!Name (~ .*-dev), mail-transport, $Version (>= 3.5)`:
341    matches all packages that provide `mail-transport` with name that has no suffix `-dev` and
342    with version greater or equal to `3.5`.
343
344When specified on command line, query may have to be quoted according to shell rules, so that it stays single argument:
345
346  `aptly repo import percona stable 'mysql-client (>= 3.6)'`
347
348## PACKAGE DISPLAY FORMAT
349
350Some aptly commands (`aptly mirror search`, `aptly package search`, ...) support `-format` flag
351which allows to customize how search results are printed. Golang templates are used to specify
352display format, with all package stanza fields available to template. In addition to package stanza
353fields aptly provides:
354
355 * `Key`:
356   internal aptly package ID, unique for all packages in aptly
357   (combination of `ShortKey` and `FilesHash`).
358
359 * `FilesHash`:
360   hash that includes MD5 of all packages files.
361
362 * `ShortKey`:
363   package ID, which is unique in single list (mirror, repo, snapshot, ...), but not unique
364   in whole aptly package collection.
365
366For example, default aptly display format could be presented with the following template:
367`{{"{{"}}.Package{{"}}"}}_{{"{{"}}.Version{{"}}"}}_{{"{{"}}.Architecture{{"}}"}}`. To display package name with dependencies:
368`{{"{{"}}.Package{{"}}"}} | {{"{{"}}.Depends{{"}}"}}`. More information on Golang template syntax: http://godoc.org/text/template
369
370## GLOBAL OPTIONS
371
372{{template "options" .}}
373
374{{template "command" findCommand . "mirror"}}
375
376{{template "command" findCommand . "repo"}}
377
378{{template "command" findCommand . "snapshot"}}
379
380{{template "command" findCommand . "publish"}}
381
382{{template "command" findCommand . "package"}}
383
384{{template "command" findCommand . "db"}}
385
386{{template "command" findCommand . "serve"}}
387
388{{template "command" findCommand . "api"}}
389
390{{template "command" findCommand . "graph"}}
391
392{{template "command" findCommand . "config"}}
393
394{{template "command" findCommand . "task"}}
395
396{{template "command" findCommand . "config"}}
397
398## ENVIRONMENT
399
400If environment variable `HTTP_PROXY` is set `aptly` would use its value
401to proxy all HTTP requests.
402
403## RETURN VALUES
404
405`aptly` exists with:
406
407 * 0:
408   success
409
410 * 1:
411   general failure
412
413 * 2:
414   command parse failure
415
416## AUTHORS
417
418{{authors}}
419
420{{end}}
421
422{{/* command list */}}
423{{define "command"}}
424{{if .Runnable}}
425## {{toUpper .Short}}
426
427{{capitalize .Parent.FullSpacedName}} {{capitalize .UsageLine}}
428
429{{.Long}}
430
431{{if (allFlags .Flag | len) gt 0}}
432Options:
433
434{{template "options" .}}
435{{end}}
436
437{{end}}
438
439{{range .Subcommands}}{{template "command" .}}{{end}}
440{{end}}
441
442{{/* options layout */}}
443{{define "options"}}
444{{range allFlags .Flag}}
445  * -`{{.Name}}`{{if ne .DefValue "false"}}={{.DefValue}}{{end}}:
446    {{.Usage}}
447{{end}}
448{{end}}
449