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