man/augtool.pod

   1 =head1 NAME
   2
   3 augtool - inspect and modify configuration files
   4
   5 =head1 SYNOPSIS
   6
   7 augtool [OPTIONS] [COMMAND]
   8
   9 =head1 DESCRIPTION
  10
  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
  14 native config files.
  15
  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
  19 encountered.
  20
  21 =head1 OPTIONS
  22
  23 =over 4
  24
  25 =item B<-c>, B<--typecheck>
  26
  27 Typecheck lenses. This can be very slow, and is therefore not done by
  28 default, but is highly recommended during development.
  29
  30 =item B<-b>, B<--backup>
  31
  32 When files are changed, preserve the originals in a file with extension
  33 '.augsave'
  34
  35 =item B<-n>, B<--new>
  36
  37 Save changes in files with extension '.augnew', do not modify the original
  38 files
  39
  40 =item B<-r>, B<--root>=I<ROOT>
  41
  42 Use directory ROOT as the root of the filesystem. Takes precedence over a
  43 root set with the AUGEAS_ROOT environment variable.
  44
  45 =item B<-I>, B<--include>=I<DIR>
  46
  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>.
  51
  52 =item B<-t>, B<--transform>=I<XFM>
  53
  54 Add a file transform; uses the 'transform' command syntax,
  55 e.g. C<-t 'Fstab incl /etc/fstab.bak'>.
  56
  57 =item B<-l>, B<--load-file>=I<FILE>
  58
  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.
  65
  66 =item B<-f>, B<--file>=I<FILE>
  67
  68 Read commands from FILE.
  69
  70 =item B<-i>, B<--interactive>
  71
  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
  74 the file.
  75
  76 =item B<-e>, B<--echo>
  77
  78 When reading commands from a file via stdin, echo the commands before
  79 printing their output.
  80
  81 =item B<-s>, B<--autosave>
  82
  83 Automatically save all changes at the end of the session.
  84
  85 =item B<-S>, B<--nostdinc>
  86
  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.
  90
  91 =item B<-L>, B<--noload>
  92
  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
  95 a C<load> command.
  96
  97 =item B<-A>, B<--noautoload>
  98
  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.
 103
 104 =item B<--span>
 105
 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.
 108
 109 =item B<--timing>
 110
 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.
 115
 116 =item B<--version>
 117
 118 Print version information and exit. The version is also in the tree under
 119 C</augeas/version>.
 120
 121 =back
 122
 123 =head1 COMMANDS
 124
 125 In interactive mode, commands and paths can be completed by pressing C<TAB>.
 126
 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.
 134
 135 =head2 ADMIN COMMANDS
 136
 137 The following commands control the behavior of Augeas and augtool itself.
 138
 139 =over 4
 140
 141 =item B<help>
 142
 143 Print this help text
 144
 145 =item B<load>
 146
 147 Load files according to the transforms in C</augeas/load>.
 148
 149 =item B<quit>
 150
 151 Exit the program
 152
 153 =item B<retrieve> E<lt>LENSE<gt> E<lt>NODE_INE<gt> E<lt>PATHE<gt> E<lt>NODE_OUTE<gt>
 154
 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.
 158
 159 =item B<save>
 160
 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.
 163
 164 =item B<store> E<lt>LENSE<gt> E<lt>NODEE<gt> E<lt>PATHE<gt>
 165
 166 Parse NODE using LENS and store the resulting tree at PATH.
 167
 168 =item B<transform> E<lt>LENSE<gt> E<lt>FILTERE<gt> E<lt>FILEE<gt>
 169
 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.
 175
 176 =item B<load-file> E<lt>FILEE<gt>
 177
 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.
 181
 182 =back
 183
 184 =head2 READ COMMANDS
 185
 186 The following commands are used to retrieve data from the Augeas tree.
 187
 188 =over 4
 189
 190 =item B<dump-xml> I<[E<lt>PATHE<gt>]>
 191
 192 Print entries in the tree as XML. If PATH is given, printing starts there,
 193 otherwise the whole tree is printed.
 194
 195 =item B<get> E<lt>PATHE<gt>
 196
 197 Print the value associated with PATH
 198
 199 =item B<label> E<lt>PATHE<gt>
 200
 201 Get and print the label associated with PATH
 202
 203 =item B<ls> E<lt>PATHE<gt>
 204
 205 List the direct children of PATH
 206
 207 =item B<match> E<lt>PATTERNE<gt> [E<lt>VALUEE<gt>]
 208
 209 Find all paths that match PATTERN. If VALUE is given, only the matching
 210 paths whose value equals VALUE are printed
 211
 212 =item B<print> I<[E<lt>PATHE<gt>]>
 213
 214 Print entries in the tree. If PATH is given, printing starts there,
 215 otherwise the whole tree is printed
 216
 217 =item B<span> E<lt>PATHE<gt>
 218
 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.
 222
 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.
 225
 226 =back
 227
 228 =head2 WRITE COMMANDS
 229
 230 The following commands are used to modify the Augeas tree.
 231
 232 =over 4
 233
 234 =item B<clear> E<lt>PATHE<gt>
 235
 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.
 238
 239 =item B<clearm> E<lt>BASEE<gt> E<lt>SUBE<gt>
 240
 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.
 244
 245 =item B<ins> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
 246
 247 Insert a new node with label LABEL right before or after PATH into the
 248 tree. WHERE must be either 'before' or 'after'.
 249
 250 =item B<insert> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
 251
 252 Alias of B<ins>.
 253
 254 =item B<mv> E<lt>SRCE<gt> E<lt>DSTE<gt>
 255
 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.
 260
 261 =item B<move> E<lt>SRCE<gt> E<lt>DSTE<gt>
 262
 263 Alias of B<mv>.
 264
 265 =item B<cp> E<lt>SRCE<gt> E<lt>DSTE<gt>
 266
 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.
 271
 272 =item B<copy> E<lt>SRCE<gt> E<lt>DSTE<gt>
 273
 274 Alias of B<cp>.
 275
 276 =item B<rename> E<lt>SRCE<gt> E<lt>LBLE<gt>
 277
 278 Rename the label of all nodes matching SRC to LBL.
 279
 280 =item B<rm> E<lt>PATHE<gt>
 281
 282 Delete PATH and all its children from the tree
 283
 284 =item B<set> E<lt>PATHE<gt> E<lt>VALUEE<gt>
 285
 286 Associate VALUE with PATH. If PATH is not in the tree yet,
 287 it and all its ancestors will be created.
 288
 289 =item B<setm> E<lt>BASEE<gt> E<lt>SUBE<gt> [E<lt>VALUEE<gt>]
 290
 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.
 294
 295 =item B<touch> E<lt>PATHE<gt>
 296
 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.
 300
 301 =back
 302
 303 =head2 PATH EXPRESSION COMMANDS
 304
 305 The following commands help when working with path expressions.
 306
 307 =over 4
 308
 309 =item B<defnode> E<lt>NAMEE<gt> E<lt>EXPRE<gt> [E<lt>VALUEE<gt>]
 310
 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.
 316
 317 =item B<defvar> E<lt>NAMEE<gt> E<lt>EXPRE<gt>
 318
 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.
 322
 323 =back
 324
 325 =head1 ENVIRONMENT VARIABLES
 326
 327 =over 4
 328
 329 =item B<AUGEAS_ROOT>
 330
 331 The file system root, defaults to '/'. Can be overridden with
 332 the B<-r> command line option
 333
 334 =item B<AUGEAS_LENS_LIB>
 335
 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>
 340
 341 =back
 342
 343 =head1 DIAGNOSTICS
 344
 345 Normally, exit status is 0. If one or more commands fail, the exit status
 346 is set to a non-zero value.
 347
 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
 352 why.
 353
 354 =head1 EXAMPLES
 355
 356   # command line mode
 357   augtool print /files/etc/hosts/
 358
 359   # interactive mode
 360   augtool
 361   augtool> help
 362   augtool> print /files/etc/hosts/
 363
 364   # Print the third entry from the second AcceptEnv line
 365   augtool print '/files/etc/ssh/sshd_config/AcceptEnv[2]/3'
 366
 367   # Find the entry in inittab with action 'initdefault'
 368   augtool> match /files/etc/inittab/*/action initdefault
 369
 370   # Print the last alias for each entry in /etc/hosts
 371   augtool> print /files/etc/hosts/*/alias[last()]
 372
 373 =head1 FILES
 374
 375 Lenses and schema definitions in F</usr/share/augeas/lenses> and
 376 F</usr/share/augeas/lenses/dist>
 377
 378 =head1 AUTHOR
 379
 380 David Lutterkort <lutter@watzmann.net>
 381
 382 =head1 COPYRIGHT AND LICENSE
 383
 384 Copyright 2007-2016 David Lutterkort
 385
 386 Augeas (and augtool) are distributed under the GNU Lesser General Public
 387 License (LGPL)
 388
 389 =head1 SEE ALSO
 390
 391 B<Augeas> project homepage L<http://www.augeas.net/>
 392
 393 B<Augeas> path expressions L<https://github.com/hercules-team/augeas/wiki/Path-expressions>
 394
 395 L<augparse>
 396
 397 L<augprint>