# Single File

**URL:** <https://hub.mender.io/t/single-file/486>\
**Category:** Update Modules\
**Created:** [April 16, 2019, 1:55pm UTC](https://hub.mender.io/t/single-file/486 "2019-04-16T13:55:59Z")\
**Posts on this page:** 1\
**Showing post:** 1

<div class="post-metadata">

**Author:** ![lluiscampos](https://yyz2.discourse-cdn.com/flex036/user_avatar/hub.mender.io/lluiscampos/32/112_2.png) [@lluiscampos](https://hub.mender.io/u/lluiscampos)\
**Post date:** [April 16, 2019, 1:55pm UTC](https://hub.mender.io/t/single-file/486/1 "2019-04-16T13:55:59Z")

</div>

### Description

The Single File Update Module installs a user defined file into a given destination directory on the device.

If the file already exists in the destination folder on the device, the Update Module will take a backup copy of it. This allows the Mender client to rollback if something goes wrong.

Example use-cases:

- Updating a single-binary application
- Updating a operating system-wide configuration file

### Specification

| | |
| --- | --- |
| Module name | single-file |
| Supports rollback | yes |
| Requires restart | no |
| Artifact generation script | yes |
| Full operating system updater | no |
| Source code | [Update Module](https://github.com/mendersoftware/mender/blob/master/support/modules/single-file), [Artifact Generator](https://github.com/mendersoftware/mender/blob/master/support/modules-artifact-gen/single-file-artifact-gen) |
| Maintainer | Northern.tech |

**It is not recommended to install a Mender Artifact on your workstation**

## Prepare the device

This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.

All commands outlined in this section should be run in the device environment.

### Prerequisites

This update module has the following prerequisites for the device environment:

- [Install the Mender client](https://docs.mender.io/client-installation/install-with-debian-package), version 2.0 or later

### Install the Update Module

Download the latest version of this Update Module by running:

```bash
mkdir -p /usr/share/mender/modules/v3 && wget -N -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender/master/support/modules/single-file

```

## Prepare the development environment on your workstation

This section describes how to set up your development environment on your workstation.

All commands outlined in this section should be run in the development environment.

### Prerequisites

This Update Modules has the following prerequisites for the development environment:

- [Install mender-artifact](https://docs.mender.io/downloads), version 3.1.0 or later

### Create Mender Artifacts

For convenience, an Artifact generator tool `single-file-artifact-gen` is provided with the Update Module. This tool will generate [Mender Artifacts](https://docs.mender.io/overview/artifact) in the same format that the Update Module expects them.

Download `single-file-artifact-gen`, by running the following command:

```bash
wget https://raw.githubusercontent.com/mendersoftware/mender/master/support/modules-artifact-gen/single-file-artifact-gen

```

Make it executable:

```bash
chmod +x single-file-artifact-gen

```

Create example file to deploy:

```bash
echo "File created by Mender single-file Update Module!" > my_file.txt

```

Now generate a Mender Artifact using the following command:

```bash
ARTIFACT_NAME="my-update-1.0"
DEVICE_TYPE="my-device-type"
OUTPUT_PATH="my-update-1.0.mender"
DEST_DIR="/opt/installed-by-single-file/"
FILE="my_file.txt"
./single-file-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -d ${DEST_DIR} -o ${OUTPUT_PATH} ${FILE}

```

- `ARTIFACT_NAME` - The name of the Mender Artifact
- `DEVICE_TYPE` - The compatible device type of this Mender Artifact
- `OUTPUT_PATH` - The path where to place the output Mender Artifact. This should always have a `.mender` suffix
- `DEST_DIR` - The path on target device where `FILE` will be installed.
- `FILE` - The path to the file to be sent to the device in the update.

You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in [Standalone deployments](https://docs.mender.io/artifact-creation/standalone-deployment).

### Artifact technical details

The Mender Artifact used by this Update Module has three payload files: a regular file with the `DEST_DIR` in plain text, a regular file with the filename of the user file in plain text, and the user file itself.

The Mender Artifact contents will look like:

```bash
Updates:
    0:
    Type: single-file
    Provides: Nothing
    Depends: Nothing
    Metadata: Nothing
    Files:
        name: dest_dir
        size: 39
        modified: 2019-04-16 15:29:40 +0200 CEST
        checksum: 58581d50870f179e80a73844f96ab3ef7dd7335aefb21562521674310fb72856
    Files:
        name: filename
        size: 12
        modified: 2019-04-16 15:29:40 +0200 CEST
        checksum: 0d6b8085d25a0eb9862ec0642f2d1e1aacbeb85d826cdeb570f19ba2719507a9
    Files:
        name: my_file.txt
        size: 60
        modified: 2019-04-16 15:29:16 +0200 CEST
        checksum: 5e93fe626d6ff553736b48c343b2d1b258960aab24b1b38496c3cf7a1fe5df51

```

---

_[View the full topic](https://hub.mender.io/t/single-file/486)._