1c2ecefae701f99793fa59f8aa8b7210e133eab9
[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 In addition to installing and removing packages, Inapt can perform
23 administrative tasks such as updating the APT package lists, applying
24 security updates, removing automatically-installed and no longer
25 needed shared libraries, and cleaning the package cache.
26
27 .SH OPTIONS
28 .TP
29 .B \-h, \-?, \-\-help
30 Display a usage message.
31 .TP
32 .B \-p, \-\-profile \fIprofile_name\fR
33 Display a usage message.
34 .TP
35 .B \-l, \-\-update
36 Update the package listings.
37 .TP
38 .B \-u, \-\-upgrade
39 Upgrade packages.
40 .TP
41 .B \-e, \-\-clean
42 Clean the package cache.
43 .TP
44 .B \-c, \-\-check
45 No action; check to see if the configuration is correct.
46 .TP
47 .B \-s, \-\-simulate
48 No action; perform a simulation of events that would occur.
49 .TP
50 .B \-\-purge
51 Use purge instead of remove for anything that would be removed.
52 .TP
53 .B \-o, \-\-option \fIconfig_string\fR
54 Set a Configuration Option; This will set an arbitrary configuration option. The syntax is -o Foo::Bar=bar.  -o and --option can be used
55 multiple times to set different options.
56 .TP
57 .B \-d
58 Enable debugging output.
59
60 .SH PROFILES
61 To allow the same configuration file to be used on many machines,
62 Inapt supports profiles. A profile is any string, such as "laptop",
63 "desktop", "web-server", or "firewall". Packages can be installed only
64 if certain profiles are selected.
65
66 You can select profiles using the --profile option on the command
67 line. Inapt will also automatically select the profile corresponding
68 to the hostname of the current machine. Finally, profiles can be
69 selected in the configuration file itself.
70
71 .SH INPUT
72 Inapt takes as input a sequence of directives. The order of directives
73 is not significant; all orderings have the same effect. It is an error
74 if directives conflict. Whitespace is also not significant, and each
75 line may be terminated by a Bourne shell style comment. Each directive
76 must be terminated by a semicolon.
77
78 .SH DIRECTIVES
79 The following directives are accepted by Inapt:
80 .TP
81 .B \fIconditional_expr\fR? \fBinstall\fR \fIpackage_list\fR;
82 Selects one or more packages to install. Inapt will not reinstall
83 packages that are already installed. If a conditional expression
84 precedes this command, the directive will be skipped if the
85 expression if false.
86 .TP
87 .B \fIconditional_expr\fR? \fBremove\fR \fIpackage_list\fR;
88 Selects one or more packages to remove. If a conditional expression
89 precedes this command, the directive will be skipped if the
90 expression if false.
91 .TP
92 .B \fIconditional_expr\fR? \fBprofiles\fR \fIprofile_name\fR \fIprofile_name\fR ...;
93 Selects one or more profiles. This is equivalent to passing the
94 --profile command line option for each named profile. If a conditional
95 expression precedes this command, the directive will be skipped if
96 the expression if false.
97 .TP
98 .B if \fIconditional_expr\fR { ... } else { ... };
99 The directives in the first block will be performed if the expression
100 is true. Otherwise, the directives in the second
101 block will be performed.
102 .TP
103 .B if \fIconditional_expr\fR { ... };
104 This is like the previous directive, except nothing is performed if
105 the expression is false.
106
107 .SH CONDITIONALS
108 A conditional expression may take any of the following forms:
109 .TP
110 .B @\fIprofile\fR
111 This expression is true if the named profile is selected and
112 false otherwise.
113 .LP
114 However, the syntax allows for more complicated
115 expressions, as follows:
116 .TP
117 .B @\fI!profile\fR
118 This expression is true if the named profile is not selected.
119 .TP
120 .B @\fIprofile\fR @\fIprofile\fR ...
121 This expression is true if all of named profiles are selected.
122 .TP
123 .B @\fIprofile/\fIprofile\fR...
124 This expression is true if any of named profiles are selected.
125 .TP
126 .B @\fIprofileA\fR/\fIprofileB\fR @\fIprofileC\fR/\fI!profileD\fR
127 This expression is true if at least one of profileA or profileB
128 is selected, and also either profileC is selected or profileD is not
129 selected.
130 .LP
131 In general, any conjunction of disjunctions of profiles or negated profiles may
132 specified using this syntax.
133
134 .SH PACKAGE LISTS
135 A package list is a whitespace separated list of package names.
136 Each package may be optionally preceded by a conditional expression.
137 If preceded by a conditional expression, a package is included in
138 the list only if the expression is true.
139
140 .SH EXAMPLES
141 .TP
142 install gcc g++ ragel;
143 Install some development tools.
144 .TP
145 remove bsdgames nethack-common gnome-games;
146 Remove some games.
147 .TP
148 @web-server install apache2-mpm-worker libapache2-mod-fcgid;
149 Install the Apache HTTP daemon and related modules, but only on the web server.
150 .TP
151 @!X remove xserver-xorg;
152 Remove the X server, but only on machines that are not supposed to have X.
153 .TP
154 profiles core;
155 Always select the core profile.
156 .TP
157 @workstation profiles development;
158 Select the development profile on all workstations.
159 .TP
160 install @X emacs22-gtk @!X emacs22-nox;
161 Install either emacs22-gtk or emacs22-nox, depending on whether the X profile is selected.
162 .SH AUTHOR
163 Inapt was written by Michael Spang <mspang@csclub.uwaterloo.ca>.
164 .SH "SEE ALSO"
165 .BR dpkg (1),
166 .BR apt-get (8),
167 .BR sources.list (5)