1AUGTOOL(1)                          Augeas                          AUGTOOL(1)
2
3
4

NAME

6       augtool - inspect and modify configuration files
7

SYNOPSIS

9       augtool [OPTIONS] [COMMAND]
10

DESCRIPTION

12       Augeas is a configuration editing tool. It parses configuration files
13       in their native formats and transforms them into a tree. Configuration
14       changes are made by manipulating this tree and saving it back into
15       native config files.
16
17       augtool provides a command line interface to the generated tree.
18       COMMAND can be a single command as described under "COMMANDS". When
19       called with no COMMAND, it reads commands from standard input until an
20       end-of-file is encountered.
21

OPTIONS

23       -c, --typecheck
24           Typecheck lenses. This can be very slow, and is therefore not done
25           by default, but is highly recommended during development.
26
27       -b, --backup
28           When files are changed, preserve the originals in a file with
29           extension '.augsave'
30
31       -n, --new
32           Save changes in files with extension '.augnew', do not modify the
33           original files
34
35       -r, --root=ROOT
36           Use directory ROOT as the root of the filesystem. Takes precedence
37           over a root set with the AUGEAS_ROOT environment variable.
38
39       -I, --include=DIR
40           Add DIR to the module loadpath. Can be given multiple times. The
41           directories set here are searched before any directories specified
42           in the AUGEAS_LENS_LIB environment variable, and before the default
43           directories /usr/share/augeas/lenses and
44           /usr/share/augeas/lenses/dist.
45
46       -t, --transform=XFM
47           Add a file transform; uses the 'transform' command syntax, e.g. "-t
48           'Fstab incl /etc/fstab.bak'".
49
50       -l, --load-file=FILE
51           Load an individual FILE into the tree. The lens to use is
52           determined automatically (based on autoload information in the
53           lenses) and will be the same that is used for this file when the
54           entire tree is loaded. The option can be specified multiple times
55           to load several files, e.g. "-l /etc/fstab -l /etc/hosts". This
56           lens implies "--noload" so that only the files specified with this
57           option will be loaded.
58
59       -f, --file=FILE
60           Read commands from FILE.
61
62       -i, --interactive
63           Read commands from the terminal. When combined with -f or
64           redirection of stdin, drop into an interactive session after
65           executing the commands from the file.
66
67       -e, --echo
68           When reading commands from a file via stdin, echo the commands
69           before printing their output.
70
71       -s, --autosave
72           Automatically save all changes at the end of the session.
73
74       -S, --nostdinc
75           Do not search any of the default directories for modules. When this
76           option is set, only directories specified explicitly with -I or
77           specified in AUGEAS_LENS_LIB will be searched for modules.
78
79       -L, --noload
80           Do not load any files on startup. This is generally used to fine-
81           tune which files to load by modifying the entries in "/augeas/load"
82           and then issuing a "load" command.
83
84       -A, --noautoload
85           Do not load any lens modules, and therefore no files, on startup.
86           This creates no entries under "/augeas/load" whatsoever; to read
87           any files, they need to be set up manually and loading must be
88           initiated with a "load" command. Using this option gives the
89           fastest startup.
90
91       --span
92           Load span positions for nodes in the tree, as they relate to the
93           original file. Enables the use of the span command to retrieve
94           position data.
95
96       --timing
97           After executing each command, print how long, in milliseconds,
98           executing the command took. This makes it easier to spot slow
99           queries, usually through match commands, and allows exploring
100           alternative queries that yield the same result but might be faster.
101
102       --version
103           Print version information and exit. The version is also in the tree
104           under "/augeas/version".
105

COMMANDS

107       In interactive mode, commands and paths can be completed by pressing
108       "TAB".
109
110       The paths accepted as arguments by commands use a small subset of XPath
111       path expressions. A path expression consists of a number of segments,
112       separated by "/". In each segment, the character "*" can be used to
113       match every node regardless of its label. Sibling nodes with identical
114       labels can be distinguished by appending "[N]" to their label to match
115       the N-th sibling with such a label. The last sibling with a specific
116       label can be reached as "[last()]". See "EXAMPLES" for some examples of
117       this.
118
119   ADMIN COMMANDS
120       The following commands control the behavior of Augeas and augtool
121       itself.
122
123       help
124           Print this help text
125
126       load
127           Load files according to the transforms in "/augeas/load".
128
129       quit
130           Exit the program
131
132       retrieve <LENS> <NODE_IN> <PATH> <NODE_OUT>
133           Transform tree at PATH back into text using lens LENS and store the
134           resulting string at NODE_OUT. Assume that the tree was initially
135           read in with the same lens and the string stored at NODE_IN as
136           input.
137
138       save
139           Save all pending changes to disk. Unless either the -b or -n
140           command line options are given, files are changed in place.
141
142       store <LENS> <NODE> <PATH>
143           Parse NODE using LENS and store the resulting tree at PATH.
144
145       transform <LENS> <FILTER> <FILE>
146           Add a transform for FILE using LENS. The LENS may be a module name
147           or a full lens name.  If a module name is given, then "lns" will be
148           the lens assumed.  The FILTER must be either "incl" or "excl".  If
149           the filter is "incl",  the FILE will be parsed by the LENS.  If the
150           filter is "excl", the FILE will be excluded from the LENS. FILE may
151           contain wildcards.
152
153       load-file <FILE>
154           Load a specific FILE, automatically determining the proper lens
155           from the information in /augeas/load; without further intervention,
156           the lens that would oridnarily be used for this file will be used.
157
158   READ COMMANDS
159       The following commands are used to retrieve data from the Augeas tree.
160
161       dump-xml [<PATH>]
162           Print entries in the tree as XML. If PATH is given, printing starts
163           there, otherwise the whole tree is printed.
164
165       get <PATH>
166           Print the value associated with PATH
167
168       label <PATH>
169           Get and print the label associated with PATH
170
171       ls <PATH>
172           List the direct children of PATH
173
174       match <PATTERN> [<VALUE>]
175           Find all paths that match PATTERN. If VALUE is given, only the
176           matching paths whose value equals VALUE are printed
177
178       print [<PATH>]
179           Print entries in the tree. If PATH is given, printing starts there,
180           otherwise the whole tree is printed
181
182       span <PATH>
183           Print the name of the file from which the node PATH was generated,
184           as well as information about the positions in the file
185           corresponding to the label, the value, and the entire node. PATH
186           must match exactly one node.
187
188           You need to run 'set /augeas/span enable' prior to loading files to
189           enable recording of span information. It is disabled by default.
190
191   WRITE COMMANDS
192       The following commands are used to modify the Augeas tree.
193
194       clear <PATH>
195           Set the value for PATH to NULL. If PATH is not in the tree yet, it
196           and all its ancestors will be created.
197
198       clearm <BASE> <SUB>
199           Clear multiple nodes values in one operation. Find or create a node
200           matching SUB by interpreting SUB as a path expression relative to
201           each node matching BASE. If SUB is '.', the nodes matching BASE
202           will be modified.
203
204       ins <LABEL> <WHERE> <PATH>
205           Insert a new node with label LABEL right before or after PATH into
206           the tree. WHERE must be either 'before' or 'after'.
207
208       insert <LABEL> <WHERE> <PATH>
209           Alias of ins.
210
211       mv <SRC> <DST>
212           Move node SRC to DST. SRC must match exactly one node in the tree.
213           DST must either match exactly one node in the tree, or may not
214           exist yet. If DST exists already, it and all its descendants are
215           deleted. If DST does not exist yet, it and all its missing
216           ancestors are created.
217
218       move <SRC> <DST>
219           Alias of mv.
220
221       cp <SRC> <DST>
222           Copy node SRC to DST. SRC must match exactly one node in the tree.
223           DST must either match exactly one node in the tree, or may not
224           exist yet. If DST exists already, it and all its descendants are
225           deleted. If DST does not exist yet, it and all its missing
226           ancestors are created.
227
228       copy <SRC> <DST>
229           Alias of cp.
230
231       rename <SRC> <LBL>
232           Rename the label of all nodes matching SRC to LBL.
233
234       rm <PATH>
235           Delete PATH and all its children from the tree
236
237       set <PATH> <VALUE>
238           Associate VALUE with PATH. If PATH is not in the tree yet, it and
239           all its ancestors will be created.
240
241       setm <BASE> <SUB> [<VALUE>]
242           Set multiple nodes in one operation.  Find or create a node
243           matching SUB by interpreting SUB as a path expression relative to
244           each node matching BASE. If SUB is '.', the nodes matching BASE
245           will be modified.
246
247       touch <PATH>
248           Create PATH with the value NULL if it is not in the tree yet.  All
249           its ancestors will also be created.  These new tree entries will
250           appear last amongst their siblings.
251
252   PATH EXPRESSION COMMANDS
253       The following commands help when working with path expressions.
254
255       defnode <NAME> <EXPR> [<VALUE>]
256           Define the variable NAME to the result of evaluating EXPR, which
257           must be a nodeset. If no node matching EXPR exists yet, one is
258           created and NAME will refer to it. If VALUE is given, this is the
259           same as 'set EXPR VALUE'; if VALUE is not given, the node is
260           created as if with 'clear EXPR' would and NAME refers to that node.
261
262       defvar <NAME> <EXPR>
263           Define the variable NAME to the result of evaluating EXPR. The
264           variable can be used in path expressions as $NAME. Note that EXPR
265           is evaluated when the variable is defined, not when it is used.
266

ENVIRONMENT VARIABLES

268       AUGEAS_ROOT
269           The file system root, defaults to '/'. Can be overridden with the
270           -r command line option
271
272       AUGEAS_LENS_LIB
273           Colon separated list of directories with lenses. Directories
274           specified here are searched after any directories set with the -I
275           command line option, but before the default directories
276           /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist
277

DIAGNOSTICS

279       Normally, exit status is 0. If one or more commands fail, the exit
280       status is set to a non-zero value.
281
282       Note though that failure to load some of the files specified by
283       transforms in "/augeas/load" is not considered a failure. If it is
284       important to know that all files were loaded, you need to issue a
285       "match /augeas//error" after loading to find out details about what
286       files could not be loaded and why.
287

EXAMPLES

289         # command line mode
290         augtool print /files/etc/hosts/
291
292         # interactive mode
293         augtool
294         augtool> help
295         augtool> print /files/etc/hosts/
296
297         # Print the third entry from the second AcceptEnv line
298         augtool print '/files/etc/ssh/sshd_config/AcceptEnv[2]/3'
299
300         # Find the entry in inittab with action 'initdefault'
301         augtool> match /files/etc/inittab/*/action initdefault
302
303         # Print the last alias for each entry in /etc/hosts
304         augtool> print /files/etc/hosts/*/alias[last()]
305

FILES

307       Lenses and schema definitions in /usr/share/augeas/lenses and
308       /usr/share/augeas/lenses/dist
309

AUTHOR

311       David Lutterkort <lutter@watzmann.net>
312
314       Copyright 2007-2016 David Lutterkort
315
316       Augeas (and augtool) are distributed under the GNU Lesser General
317       Public License (LGPL)
318

SEE ALSO

320       Augeas project homepage <http://www.augeas.net/>
321
322       augparse
323
324
325
326Augeas 1.5.0                      2016-08-05                        AUGTOOL(1)
Impressum