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
|
.Dd October 28, 2023
.Dt HSCRIPT-IMAGE 1
.Os "Adélie Linux"
.Sh NAME
.Nm hscript-image
.Nd create an image based on a HorizonScript for later deployment
.Sh SYNOPSIS
.Nm
.Op Fl e Ar DIRECTORY
.Op Fl h
.Op Fl i Ar DIRECTORY
.Op Fl n
.Op Fl o Ar OUTPUT-FILE
.Op Fl t Ar TYPE
.Op Fl v
.Op Ar INSTALLFILE
.Sh DESCRIPTION
The
.Nm
utility creates an image of an operating environment. The environment is
configured per a provided HorizonScript file.
.Ss Image Creation
The
.Nm
utility first executes the HorizonScript in a temporary directory, called
the
.Em intermediate directory .
From there, the
.Nm
utility then creates the image using the files present in the intermediate
directory. The intermediate directory is not removed after image creation,
allowing inspection of the files used to create the image.
.Ss Image Formats
The
.Nm
utility can be extended with new image formats by writing a new backend.
The backends included with the default distribution include:
.Bl -tag -width Ds
.It tar
Creates a pax-extended ustar archive. See
.Xr 1p pax
for a description of the on-disk format. This archive may be extracted to
the desired system at a later time.
.It tgz, tbz, txz
Creates a pax-extended ustar archive, like tar, but additionally compresses
the archive with
.Xr 1 gzip
(tgz),
.Xr 1 bzip2
(tbz), or
.Xr 1 xz
(txz).
.El
.Sh OPTIONS
The
.Nm
utility supports the following options:
.Bl -tag -width Ds
.It Fl h
Prints a short help message to the current terminal and exits.
.It Fl i Ar DIRECTORY
Sets the intermediate directory to
.Ar DIRECTORY .
.It Fl n
Disables colour output and ANSI escapes when writing log output. This is
the default mode when not running on a terminal.
.It Fl o Ar OUTPUT-FILE
Writes the image to
.Ar OUTPUT-FILE
instead of the backend default (typically
.Qq image.tar
or similar).
.It Fl t Ar TYPE
Sets the image type to
.Ar TYPE .
A list of image types supported by your copy of the
.Nm
utility can be obtained by specifying
.Cm list
as the argument to
.Fl t .
.It Fl v
Displays the version information for this utility, and then exits.
.It Fl e Ar DIRECTORY
Sets the qemu-static binary directory to
.Ar DIRECTORY .
This must be equivalent to the configuration of binfmt-misc on the host.
The default is
.Pa /usr/bin ,
and typically should not be changed unless you have a very good reason.
.It Ar INSTALLFILE
Specifies the location of the HorizonScript to use for configuring the image.
You may specify
.Qq -
to read from standard input.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/horizon/installfile
This is the default location for the HorizonScript to be read, if it is not
specified on the command line.
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
The following invocation creates a XZ-compressed pax archive named
.Qq myimage.tar.xz
using the configuration contained in the HorizonScript at
.Pa /srv/scripts/myimage.installfile .
.Dl $ hscript-image -t txz -o myimage.tar.xz /srv/scripts/myimage.installfile
.Pp
The following invocation creates a pax archive named
.Qq myimage.tar
using the configuration contained in the HorizonScript at
.Pa /srv/scripts/myimage.installfile ,
using
.Pa /tmp/image-ir
as the intermediate directory:
.Dl $ hscript-image -o myimage.tar -i /tmp/image-ir /srv/scripts/myimage.installfile
.Sh DIAGNOSTICS
.Bl -diag
.It "%dateT%time log %location: %status: %message[: %extra]"
A message of type
.Cm %status
was logged while processing
.Cm %location .
The log message
.Cm %message
may be followed by additional information or hints in
.Cm %extra .
.It "%dateT%time step-start %step"
Denotes that the installation step
.Cm %step
is starting. Steps are described in the
.Sy Steps
section of the
.Xr hscript-executor 8
manual.
.It "%dateT%time step-end %step"
Denotes that the installation step
.Cm %step
has finished successfully. Steps are described in the
.Sy Steps
section of the
.Xr hscript-executor 8
manual.
.El
.Sh SEE ALSO
.Xr hscript-validate 1 ,
.Xr hscript 5 ,
.Xr hscript-executor 8 .
.Sh HISTORY
The
.Nm
command first appeared in Horizon 0.9.
.Sh AUTHORS
.An A. Wilcox
.Aq awilfox@adelielinux.org
|
