# download

download a file or an archive

The host fetches the file and checks its sha256. A download with another checksum fails and keeps the old file. A step has path or unpack.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`url`](#download.url) | string | required | fetched by the host |
| [`sha256`](#download.sha256) | string | required | checksum of the file |
| [`path`](#download.path) | string | - | absolute target of a single file |
| [`unpack`](#download.unpack) | string | - | directory for the unpacked archive |
| [`owner`](#download.owner) | name or ID | root | of the file or the unpacked tree |
| [`group`](#download.group) | name or ID | root | of the file or the unpacked tree |
| [`mode`](#download.mode) | string | 0644 | octal, in quotes; path only |

### `download.url` {#download.url}

string, required

Fetched by the host.

### `download.sha256` {#download.sha256}

string, required

Checksum of the file. Take the value from the checksum file that the vendor publishes, or download the file once and run sha256sum on it. A download with another checksum fails and keeps the old file.

### `download.path` {#download.path}

string

Absolute target of a single file. A step has path or unpack.

### `download.unpack` {#download.unpack}

string

Directory for the unpacked archive. The path of the URL ends in .tar.gz, .tgz, .tar.xz, or .zip. The directory holds the entries of the archive as they are: a top directory of the archive stays, as in \<unpack\>/app-1.2/bin. The step unpacks again when sha256, owner, group, or the directory changes. Each unpack replaces the whole tree, also the first: it removes the files that are already in the directory. Keep the files that a program writes, such as its config, data, and logs, outside the directory.

### `download.owner` {#download.owner}

name or ID, default root

Of the file or the unpacked tree. A user name or a numeric ID.

### `download.group` {#download.group}

name or ID, default root

Of the file or the unpacked tree. A group name or a numeric ID.

### `download.mode` {#download.mode}

string, default 0644

Octal, in quotes; path only. Without quotes, YAML reads it as a number. With unpack, mode is an error: the entries keep the modes of the archive, without write permission for group and others.

## Example

```yaml
- download:
    url: https://example.com/releases/app-1.4.2-linux-amd64
    sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
    path: /usr/local/bin/app
    mode: "0755"
```