3 augtool - inspect and modify configuration files
7 augtool [OPTIONS] [COMMAND]
11 Augeas is a configuration editing tool. It parses configuration files
12 in their native formats and transforms them into a tree. Configuration
13 changes are made by manipulating this tree and saving it back into
16 augtool provides a command line interface to the generated tree. COMMAND
17 can be a single command as described under L</COMMANDS>. When called with
18 no COMMAND, it reads commands from standard input until an end-of-file is
25 =item B<-c>, B<--typecheck>
27 Typecheck lenses. This can be very slow, and is therefore not done by
28 default, but is highly recommended during development.
30 =item B<-b>, B<--backup>
32 When files are changed, preserve the originals in a file with extension
37 Save changes in files with extension '.augnew', do not modify the original
40 =item B<-r>, B<--root>=I<ROOT>
42 Use directory ROOT as the root of the filesystem. Takes precedence over a
43 root set with the AUGEAS_ROOT environment variable.
45 =item B<-I>, B<--include>=I<DIR>
47 Add DIR to the module loadpath. Can be given multiple times. The
48 directories set here are searched before any directories specified in the
49 AUGEAS_LENS_LIB environment variable, and before the default directories
50 F</usr/share/augeas/lenses> and F</usr/share/augeas/lenses/dist>.
52 =item B<-t>, B<--transform>=I<XFM>
54 Add a file transform; uses the 'transform' command syntax,
55 e.g. C<-t 'Fstab incl /etc/fstab.bak'>.
57 =item B<-l>, B<--load-file>=I<FILE>
59 Load an individual FILE into the tree. The lens to use is determined
60 automatically (based on autoload information in the lenses) and will be the
61 same that is used for this file when the entire tree is loaded. The option
62 can be specified multiple times to load several files, e.g. C<-l /etc/fstab
63 -l /etc/hosts>. This lens implies C<--noload> so that only the files
64 specified with this option will be loaded.
66 =item B<-f>, B<--file>=I<FILE>
68 Read commands from FILE.
70 =item B<-i>, B<--interactive>
72 Read commands from the terminal. When combined with B<-f> or redirection of
73 stdin, drop into an interactive session after executing the commands from
76 =item B<-e>, B<--echo>
78 When reading commands from a file via stdin, echo the commands before
79 printing their output.
81 =item B<-s>, B<--autosave>
83 Automatically save all changes at the end of the session.
85 =item B<-S>, B<--nostdinc>
87 Do not search any of the default directories for modules. When this option
88 is set, only directories specified explicitly with B<-I> or specified in
89 B<AUGEAS_LENS_LIB> will be searched for modules.
91 =item B<-L>, B<--noload>
93 Do not load any files on startup. This is generally used to fine-tune which
94 files to load by modifying the entries in C</augeas/load> and then issuing
97 =item B<-A>, B<--noautoload>
99 Do not load any lens modules, and therefore no files, on startup. This
100 creates no entries under C</augeas/load> whatsoever; to read any files,
101 they need to be set up manually and loading must be initiated with a
102 C<load> command. Using this option gives the fastest startup.
106 Load span positions for nodes in the tree, as they relate to the original
107 file. Enables the use of the B<span> command to retrieve position data.
111 After executing each command, print how long, in milliseconds, executing
112 the command took. This makes it easier to spot slow queries, usually
113 through B<match> commands, and allows exploring alternative queries that
114 yield the same result but might be faster.
118 Print version information and exit. The version is also in the tree under
125 In interactive mode, commands and paths can be completed by pressing C<TAB>.
127 The paths accepted as arguments by commands use a small subset of XPath
128 path expressions. A path expression consists of a number of segments,
129 separated by C</>. In each segment, the character C<*> can be used to match
130 every node regardless of its label. Sibling nodes with identical labels can
131 be distinguished by appending C<[N]> to their label to match the N-th
132 sibling with such a label. The last sibling with a specific label can be
133 reached as C<[last()]>. See L</EXAMPLES> for some examples of this.
135 =head2 ADMIN COMMANDS
137 The following commands control the behavior of Augeas and augtool itself.
147 Load files according to the transforms in C</augeas/load>.
153 =item B<retrieve> E<lt>LENSE<gt> E<lt>NODE_INE<gt> E<lt>PATHE<gt> E<lt>NODE_OUTE<gt>
155 Transform tree at PATH back into text using lens LENS and store the
156 resulting string at NODE_OUT. Assume that the tree was initially read in
157 with the same lens and the string stored at NODE_IN as input.
161 Save all pending changes to disk. Unless either the B<-b> or B<-n>
162 command line options are given, files are changed in place.
164 =item B<store> E<lt>LENSE<gt> E<lt>NODEE<gt> E<lt>PATHE<gt>
166 Parse NODE using LENS and store the resulting tree at PATH.
168 =item B<transform> E<lt>LENSE<gt> E<lt>FILTERE<gt> E<lt>FILEE<gt>
170 Add a transform for FILE using LENS. The LENS may be a module name or a
171 full lens name. If a module name is given, then "lns" will be the lens
172 assumed. The FILTER must be either "incl" or "excl". If the filter is
173 "incl", the FILE will be parsed by the LENS. If the filter is "excl",
174 the FILE will be excluded from the LENS. FILE may contain wildcards.
176 =item B<load-file> E<lt>FILEE<gt>
178 Load a specific FILE, automatically determining the proper lens from the
179 information in F</augeas/load>; without further intervention, the lens that
180 would oridnarily be used for this file will be used.
186 The following commands are used to retrieve data from the Augeas tree.
190 =item B<dump-xml> I<[E<lt>PATHE<gt>]>
192 Print entries in the tree as XML. If PATH is given, printing starts there,
193 otherwise the whole tree is printed.
195 =item B<get> E<lt>PATHE<gt>
197 Print the value associated with PATH
199 =item B<label> E<lt>PATHE<gt>
201 Get and print the label associated with PATH
203 =item B<ls> E<lt>PATHE<gt>
205 List the direct children of PATH
207 =item B<match> E<lt>PATTERNE<gt> [E<lt>VALUEE<gt>]
209 Find all paths that match PATTERN. If VALUE is given, only the matching
210 paths whose value equals VALUE are printed
212 =item B<print> I<[E<lt>PATHE<gt>]>
214 Print entries in the tree. If PATH is given, printing starts there,
215 otherwise the whole tree is printed
217 =item B<span> E<lt>PATHE<gt>
219 Print the name of the file from which the node PATH was generated, as well
220 as information about the positions in the file corresponding to the label,
221 the value, and the entire node. PATH must match exactly one node.
223 You need to run 'set /augeas/span enable' prior to loading files to enable
224 recording of span information. It is disabled by default.
228 =head2 WRITE COMMANDS
230 The following commands are used to modify the Augeas tree.
234 =item B<clear> E<lt>PATHE<gt>
236 Set the value for PATH to NULL. If PATH is not in the tree yet, it and all
237 its ancestors will be created.
239 =item B<clearm> E<lt>BASEE<gt> E<lt>SUBE<gt>
241 Clear multiple nodes values in one operation. Find or create a node matching SUB
242 by interpreting SUB as a path expression relative to each node matching
243 BASE. If SUB is '.', the nodes matching BASE will be modified.
245 =item B<ins> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
247 Insert a new node with label LABEL right before or after PATH into the
248 tree. WHERE must be either 'before' or 'after'.
250 =item B<insert> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
254 =item B<mv> E<lt>SRCE<gt> E<lt>DSTE<gt>
256 Move node SRC to DST. SRC must match exactly one node in the tree. DST
257 must either match exactly one node in the tree, or may not exist yet. If
258 DST exists already, it and all its descendants are deleted. If DST does not
259 exist yet, it and all its missing ancestors are created.
261 =item B<move> E<lt>SRCE<gt> E<lt>DSTE<gt>
265 =item B<cp> E<lt>SRCE<gt> E<lt>DSTE<gt>
267 Copy node SRC to DST. SRC must match exactly one node in the tree. DST
268 must either match exactly one node in the tree, or may not exist yet. If
269 DST exists already, it and all its descendants are deleted. If DST does not
270 exist yet, it and all its missing ancestors are created.
272 =item B<copy> E<lt>SRCE<gt> E<lt>DSTE<gt>
276 =item B<rename> E<lt>SRCE<gt> E<lt>LBLE<gt>
278 Rename the label of all nodes matching SRC to LBL.
280 =item B<rm> E<lt>PATHE<gt>
282 Delete PATH and all its children from the tree
284 =item B<set> E<lt>PATHE<gt> E<lt>VALUEE<gt>
286 Associate VALUE with PATH. If PATH is not in the tree yet,
287 it and all its ancestors will be created.
289 =item B<setm> E<lt>BASEE<gt> E<lt>SUBE<gt> [E<lt>VALUEE<gt>]
291 Set multiple nodes in one operation. Find or create a node matching SUB by
292 interpreting SUB as a path expression relative to each node matching
293 BASE. If SUB is '.', the nodes matching BASE will be modified.
295 =item B<touch> E<lt>PATHE<gt>
297 Create PATH with the value NULL if it is not in the tree yet. All its
298 ancestors will also be created. These new tree entries will appear
299 last amongst their siblings.
303 =head2 PATH EXPRESSION COMMANDS
305 The following commands help when working with path expressions.
309 =item B<defnode> E<lt>NAMEE<gt> E<lt>EXPRE<gt> [E<lt>VALUEE<gt>]
311 Define the variable NAME to the result of evaluating EXPR, which must be a
312 nodeset. If no node matching EXPR exists yet, one is created and NAME will
313 refer to it. If VALUE is given, this is the same as 'set EXPR VALUE'; if
314 VALUE is not given, the node is created as if with 'clear EXPR' would and
315 NAME refers to that node.
317 =item B<defvar> E<lt>NAMEE<gt> E<lt>EXPRE<gt>
319 Define the variable NAME to the result of evaluating EXPR. The variable
320 can be used in path expressions as $NAME. Note that EXPR is evaluated when
321 the variable is defined, not when it is used.
325 =head1 ENVIRONMENT VARIABLES
331 The file system root, defaults to '/'. Can be overridden with
332 the B<-r> command line option
334 =item B<AUGEAS_LENS_LIB>
336 Colon separated list of directories with lenses. Directories specified here
337 are searched after any directories set with the B<-I> command line option,
338 but before the default directories F</usr/share/augeas/lenses> and
339 F</usr/share/augeas/lenses/dist>
345 Normally, exit status is 0. If one or more commands fail, the exit status
346 is set to a non-zero value.
348 Note though that failure to load some of the files specified by transforms
349 in C</augeas/load> is not considered a failure. If it is important to know
350 that all files were loaded, you need to issue a C<match /augeas//error>
351 after loading to find out details about what files could not be loaded and
357 augtool print /files/etc/hosts/
362 augtool> print /files/etc/hosts/
364 # Print the third entry from the second AcceptEnv line
365 augtool print '/files/etc/ssh/sshd_config/AcceptEnv[2]/3'
367 # Find the entry in inittab with action 'initdefault'
368 augtool> match /files/etc/inittab/*/action initdefault
370 # Print the last alias for each entry in /etc/hosts
371 augtool> print /files/etc/hosts/*/alias[last()]
375 Lenses and schema definitions in F</usr/share/augeas/lenses> and
376 F</usr/share/augeas/lenses/dist>
380 David Lutterkort <lutter@watzmann.net>
382 =head1 COPYRIGHT AND LICENSE
384 Copyright 2007-2016 David Lutterkort
386 Augeas (and augtool) are distributed under the GNU Lesser General Public
391 B<Augeas> project homepage L<http://www.augeas.net/>
393 B<Augeas> path expressions L<https://github.com/hercules-team/augeas/wiki/Path-expressions>