1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
[](https://gitlab.com/Northern.tech/Mender/mender-artifact/pipelines)
[](https://coveralls.io/github/mendersoftware/mender-artifact?branch=master)
[](https://goreportcard.com/report/github.com/mendersoftware/mender-artifact)
Mender Artifacts Library
==============================================
Mender is an open source over-the-air (OTA) software updater for embedded Linux
devices. Mender comprises a client running at the embedded device, as well as
a server that manages deployments across many devices.
This repository contains the artifacts library, which is used by the
Mender client, command line interface, server and for build integration with the Yocto Project.
The artifacts library makes it easy to programmatically work with a Mender artifact, which
is a file that can be recognized by its `.mender` suffix. Mender artifacts
can contain binaries, metadata, checksums, signatures and scripts that are
used during a deployment. The artifact format acts as a wrapper, and
uses the `tar` format to bundle several files into one.
In its simplest form, an artifact contains just a rootfs image,
along with its checksum, id and device type compatibility.
The artifacts library might also be useful for other updaters or
purposes. We are always happy to see other uses of it!
## Getting started
To start using Mender, we recommend that you begin with the Getting started
section in [the Mender documentation](https://docs.mender.io/).
## Using the library
You can use the reader and the writer in go in the standard way:
```
import (
"github.com/mendersoftware/mender-artifact/areader"
"github.com/mendersoftware/mender-artifact/awriter"
...
)
```
For sample usage, please see the [Mender client source code](https://github.com/mendersoftware/mender).
## Downloading the binaries
You can find the latest `mender-artifact` binaries in the [Downloads page on
Mender Docs](https://docs.mender.io/downloads).
These binaries are built using the containerized method described below, hence using the
`Dockerfile`(s) from this repository with the Go version specified there.
Additionally, `mender-artifact` is distributed in source flavor for Yocto recipes in
[`meta-mender`](https://github.com/mendersoftware/meta-mender/tree/master/meta-mender-core/recipes-mender/mender-artifact)
and as Debian/Ubuntu binary packages in [Mender APT
repositories](https://docs.mender.io/downloads#install-using-the-apt-repository). For these the Go
version to use is determined by the Yocto or Debian/Ubuntu distribution in use.
## Building from source
**Note: The build process is only supported on Linux-based environments.**
### Containerized
The preferred way to build `mender-artifact` from source is containerized in `docker`.
This process can be used to generate binaries suitable for running on Linux, Windows and MacOS
hosts.
You need the following prerequisites:
- docker [Installation instructions](https://docs.docker.com/get-docker/)
- the `make` tool. Most distributions offer a `make` package. Install it using your native
package management tool, such as `apt`, `yum`, `pacman`, ...
In the source directory, build `mender-artifact` by issueing
```
make build-natives-contained
```
This results in the self-contained binary `mender-artifact`. You can leave it in place,
or move it to a location on your systems `PATH`.
**Note: containerized building on non-x86 platform is not supported yet**
### Native
To build `mender-artifact` from source you need the following prerequisites:
(packages given for Debian-based environments)
- the Go programming language. [Installation instructions](https://go.dev/doc/install)
- the packages `build-essential liblzma-dev libssl-dev pkg-config`
In the source directory, `mender-artifact` is built by simply issueing
```
make
```
This results in the self-contained binary `mender-artifact`. You can leave it in place,
or move it to a location on your systems `PATH`.
## Enabling auto-completion in Bash & ZSH
### Automatic installation through the Makefile
This is the easiest approach, and all that is needed it to run:
```bash
sudo make install-autocomplete-scripts
```
And the `Bash` auto-complete script will be installed to
`/etc/bash_completion.d`, and if `Zsh` is installed on the system, the
corresponding auto-completion script is installed into
`/usr/local/share/zsh/site-functions`.
You can override both the `DESTDIR` (default: empty) and `PREFIX` (default: `/usr/local`) variables to alter the destination paths, i.e:
```bash
sudo make DESTDIR=/tmp PREFIX=/usr install-autocomplete-scripts
```
### Manual installation
auto-completion of `mender-artifact` sub-commands can be added to either ZSH or
Bash through:
#### Bash
The simplest way of enabling auto-completion in Bash is to copy the
`./autocomplete/bash_autocomplete` file into `/etc/bash_completion.d/` like so:
```bash
sudo cp path/to/mender-aritfact/autocomplete/bash_autocomplete /etc/bash_completion.d/mender-artifact
source /etc/bash_completion.d/mender-artifact
```
Alternatively the following can be added to `.bashrc`:
```bash
PROG=mender-artifact
source path/to/mender-artifact/autocomplete/bash_autocomplete
```
#### ZSH
Auto-completion for ZSH is supported through the `zsh_autocompletion` script
found in the `./autocomplete` directory. In order to enable it consistently, add
these lines to your `.zshrc` file:
```bash
source path/to/mender-artifact/autocomplete/zsh_autocomplete
```
## Contributing
We welcome and ask for your contribution. If you would like to contribute to Mender, please read our guide on how to best get started [contributing code or
documentation](https://github.com/mendersoftware/mender/blob/master/CONTRIBUTING.md).
## License
Mender is licensed under the Apache License, Version 2.0. See
[LICENSE](https://github.com/mendersoftware/artifacts/blob/master/LICENSE) for the
full license text.
## Security disclosure
We take security very seriously. If you come across any issue regarding
security, please disclose the information by sending an email to
[security@mender.io](security@mender.io). Please do not create a new public
issue. We thank you in advance for your cooperation.
## Connect with us
* Join the [Mender Hub discussion forum](https://hub.mender.io)
* Follow us on [Twitter](https://twitter.com/mender_io). Please
feel free to tweet us questions.
* Fork us on [Github](https://github.com/mendersoftware)
* Create an issue in the [bugtracker](https://northerntech.atlassian.net/projects/MEN)
* Email us at [contact@mender.io](mailto:contact@mender.io)
* Connect to the [#mender IRC channel on Libera](https://web.libera.chat/?#mender)
|
