Merge pull request #4 from jeremyroman/master
[mspang/inapt.git] / inapt.8
1 .TH INAPT 8 "December 26, 2009"
2 .SH NAME
3 inapt \- manages installed packages with a configuration file
4 .SH SYNOPSIS
5 .B inapt
6 .RI [ options ] " files" ...
7 .SH DESCRIPTION
8 Inapt is a frontend to APT that installs and removes packages
9 according to a configuration file. This is useful primarily if a
10 similar set of packages must be installed on a large number of
11 machines. It is also allows the installed packages to be version
12 controlled. The configuration file syntax allows for packages to be
13 installed conditionally upon a set of profiles assigned to each
14 machine.
15
16 The input language for Inapt is declarative, so that if all desired
17 packages are already installed then Inapt will take no action. This
18 makes Inapt suitable for running regularly to inspect the system
19 configuration and make sure nothing is amiss. A usual approach would
20 be to run Inapt in a nightly cron job.
21
22 .SH OPTIONS
23 .TP
24 .B \-h, \-?, \-\-help
25 Display a usage message.
26 .TP
27 .B \-p, \-\-profile \fIprofile_name\fR
28 Enable the specified profile.
29 .TP
30 .B \-s, \-\-simulate
31 No action; perform a simulation of events that would occur.
32 .TP
33 .B \-t, \-\-strict
34 Abort the install if a package cannot be found.
35 .TP
36 .B \-\-purge
37 Use purge instead of remove for anything that would be removed.
38 .TP
39 .B \-o, \-\-option \fIconfig_string\fR
40 Set an APT configuration option; This will set an arbitrary configuration option. The syntax is -o Foo::Bar=bar.  -o and --option can be used
41 multiple times to set different options.
42 .TP
43 .B \-d
44 Enable debugging output.
45
46 .SH PROFILES
47 To allow the same configuration file to be used on many machines,
48 Inapt supports profiles. A profile is any string, such as "laptop",
49 "desktop", "web-server", or "firewall". Packages can be installed only
50 if certain profiles are selected.
51
52 You can select profiles using the --profile option on the command
53 line. Inapt will also automatically select the profile corresponding
54 to the hostname of the current machine. Finally, profiles can be
55 selected in the configuration file itself.
56
57 .SH INPUT
58 Inapt takes as input a sequence of directives. Unless otherwise noted,
59 the order of directives is not significant. It is an error if
60 directives conflict. Whitespace is also not significant, and each line
61 may be terminated by a Bourne shell style comment. Each directive must
62 be terminated by a semicolon.
63
64 .SH DIRECTIVES
65 The following directives are accepted by Inapt:
66 .TP
67 .B \fIconditional_expr\fR? \fBinstall\fR \fIpackage_list\fR;
68 Selects one or more packages to install. Inapt will not reinstall
69 packages that are already installed. If a conditional expression
70 precedes this command, the directive will be skipped if the
71 expression if false.
72 .TP
73 .B \fIconditional_expr\fR? \fBremove\fR \fIpackage_list\fR;
74 Selects one or more packages to remove. If a conditional expression
75 precedes this command, the directive will be skipped if the
76 expression if false.
77 .TP
78 .B \fIconditional_expr\fR? \fBprofiles\fR \fIprofile_name\fR \fIprofile_name\fR ...;
79 Selects one or more profiles. This is equivalent to passing the
80 --profile command line option for each named profile. If a conditional
81 expression precedes this command, the directive will be skipped if
82 the expression if false.
83 .TP
84 .B if \fIconditional_expr\fR { ... } else { ... };
85 The directives in the first block will be performed if the expression
86 is true. Otherwise, the directives in the second
87 block will be performed.
88 .TP
89 .B if \fIconditional_expr\fR { ... };
90 This is like the previous directive, except nothing is performed if
91 the expression is false.
92
93 .SH CONDITIONALS
94 A conditional expression may take any of the following forms:
95 .TP
96 .B @\fIprofile\fR
97 This expression is true if the named profile is selected and
98 false otherwise.
99 .LP
100 However, the syntax allows for more complicated
101 expressions, as follows:
102 .TP
103 .B @\fI!profile\fR
104 This expression is true if the named profile is not selected.
105 .TP
106 .B @\fIprofile\fR @\fIprofile\fR ...
107 This expression is true if all of named profiles are selected.
108 .TP
109 .B @\fIprofile/\fIprofile\fR...
110 This expression is true if any of named profiles are selected.
111 .TP
112 .B @\fIprofileA\fR/\fIprofileB\fR @\fIprofileC\fR/\fI!profileD\fR
113 This expression is true if at least one of profileA or profileB
114 is selected, and also either profileC is selected or profileD is not
115 selected.
116 .LP
117 In general, any conjunction of disjunctions of profiles or negated profiles may
118 specified using this syntax.
119
120 .SH PACKAGE LISTS
121 A package list is a whitespace separated list of package names.
122 Each package may be optionally preceded by a conditional expression.
123 If preceded by a conditional expression, a package is included in
124 the list only if the expression is true.
125
126 .SH EXAMPLES
127 .TP
128 install gcc g++ ragel;
129 Install some development tools.
130 .TP
131 remove bsdgames nethack-common gnome-games;
132 Remove some games.
133 .TP
134 @web-server install apache2-mpm-worker libapache2-mod-fcgid;
135 Install the Apache HTTP daemon and related modules, but only on the web server.
136 .TP
137 @!X remove xserver-xorg;
138 Remove the X server, but only on machines that are not supposed to have X.
139 .TP
140 profiles core;
141 Always select the core profile.
142 .TP
143 @workstation profiles development;
144 Select the development profile on all workstations.
145 .TP
146 install @X emacs22-gtk @!X emacs22-nox;
147 Install either emacs22-gtk or emacs22-nox, depending on whether the X profile is selected.
148 .SH AUTHOR
149 Inapt was written by Michael Spang <mspang@csclub.uwaterloo.ca>.
150 .SH "SEE ALSO"
151 .BR dpkg (1),
152 .BR apt-get (8),
153 .BR sources.list (5)