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<-f>, B<--file>=I<FILE>
  58
  59 Read commands from FILE.
  60
  61 =item B<-i>, B<--interactive>
  62
  63 Read commands from the terminal. When combined with B<-f> or redirection of
  64 stdin, drop into an interactive session after executing the commands from
  65 the file.
  66
  67 =item B<-e>, B<--echo>
  68
  69 When reading commands from a file via stdin, echo the commands before
  70 printing their output.
  71
  72 =item B<-s>, B<--autosave>
  73
  74 Automatically save all changes at the end of the session.
  75
  76 =item B<-S>, B<--nostdinc>
  77
  78 Do not search any of the default directories for modules. When this option
  79 is set, only directories specified explicitly with B<-I> or specified in
  80 B<AUGEAS_LENS_LIB> will be searched for modules.
  81
  82 =item B<-L>, B<--noload>
  83
  84 Do not load any files on startup. This is generally used to fine-tune which
  85 files to load by modifying the entries in C</augeas/load> and then issuing
  86 a C<load> command.
  87
  88 =item B<-A>, B<--noautoload>
  89
  90 Do not load any lens modules, and therefore no files, on startup. This
  91 creates no entries under C</augeas/load> whatsoever; to read any files,
  92 they need to be set up manually and loading must be initiated with a
  93 C<load> command. Using this option gives the fastest startup.
  94
  95 =item B<--span>
  96
  97 Load span positions for nodes in the tree, as they relate to the original
  98 file. Enables the use of the B<span> command to retrieve position data.
  99
 100 =item B<--version>
 101
 102 Print version information and exit. The version is also in the tree under
 103 C</augeas/version>.
 104
 105 =back
 106
 107 =head1 COMMANDS
 108
 109 In interactive mode, commands and paths can be completed by pressing C<TAB>.
 110
 111 The paths accepted as arguments by commands use a small subset of XPath
 112 path expressions. A path expression consists of a number of segments,
 113 separated by C</>. In each segment, the character C<*> can be used to match
 114 every node regardless of its label. Sibling nodes with identical labels can
 115 be distinguished by appending C<[N]> to their label to match the N-th
 116 sibling with such a label. The last sibling with a specific label can be
 117 reached as C<[last()]>. See L</EXAMPLES> for some examples of this.
 118
 119 =head2 ADMIN COMMANDS
 120
 121 The following commands control the behavior of Augeas and augtool itself.
 122
 123 =over 4
 124
 125 =item B<help>
 126
 127 Print this help text
 128
 129 =item B<load>
 130
 131 Load files according to the transforms in C</augeas/load>.
 132
 133 =item B<quit>
 134
 135 Exit the program
 136
 137 =item B<retrieve> E<lt>LENSE<gt> E<lt>NODE_INE<gt> E<lt>PATHE<gt> E<lt>NODE_OUTE<gt>
 138
 139 Transform tree at PATH back into text using lens LENS and store the
 140 resulting string at NODE_OUT. Assume that the tree was initially read in
 141 with the same lens and the string stored at NODE_IN as input.
 142
 143 =item B<save>
 144
 145 Save all pending changes to disk. Unless either the B<-b> or B<-n>
 146 command line options are given, files are changed in place.
 147
 148 =item B<store> E<lt>LENSE<gt> E<lt>NODEE<gt> E<lt>PATHE<gt>
 149
 150 Parse NODE using LENS and store the resulting tree at PATH.
 151
 152 =item B<transform> E<lt>LENSE<gt> E<lt>FILTERE<gt> E<lt>FILEE<gt>
 153
 154 Add a transform for FILE using LENS. The LENS may be a module name or a
 155 full lens name.  If a module name is given, then "lns" will be the lens
 156 assumed.  The FILTER must be either "incl" or "excl".  If the filter is
 157 "incl",  the FILE will be parsed by the LENS.  If the filter is "excl",
 158 the FILE will be excluded from the LENS. FILE may contain wildcards.
 159
 160 =back
 161
 162 =head2 READ COMMANDS
 163
 164 The following commands are used to retrieve data from the Augeas tree.
 165
 166 =over 4
 167
 168 =item B<dump-xml> I<[E<lt>PATHE<gt>]>
 169
 170 Print entries in the tree as XML. If PATH is given, printing starts there,
 171 otherwise the whole tree is printed.
 172
 173 =item B<get> E<lt>PATHE<gt>
 174
 175 Print the value associated with PATH
 176
 177 =item B<label> E<lt>PATHE<gt>
 178
 179 Get and print the label associated with PATH
 180
 181 =item B<ls> E<lt>PATHE<gt>
 182
 183 List the direct children of PATH
 184
 185 =item B<match> E<lt>PATTERNE<gt> [E<lt>VALUEE<gt>]
 186
 187 Find all paths that match PATTERN. If VALUE is given, only the matching
 188 paths whose value equals VALUE are printed
 189
 190 =item B<print> I<[E<lt>PATHE<gt>]>
 191
 192 Print entries in the tree. If PATH is given, printing starts there,
 193 otherwise the whole tree is printed
 194
 195 =item B<span> E<lt>PATHE<gt>
 196
 197 Print the name of the file from which the node PATH was generated, as well
 198 as information about the positions in the file corresponding to the label,
 199 the value, and the entire node. PATH must match exactly one node.
 200
 201 You need to run 'set /augeas/span enable' prior to loading files to enable
 202 recording of span information. It is disabled by default.
 203
 204 =back
 205
 206 =head2 WRITE COMMANDS
 207
 208 The following commands are used to modify the Augeas tree.
 209
 210 =over 4
 211
 212 =item B<clear> E<lt>PATHE<gt>
 213
 214 Set the value for PATH to NULL. If PATH is not in the tree yet, it and all
 215 its ancestors will be created.
 216
 217 =item B<clearm> E<lt>BASEE<gt> E<lt>SUBE<gt>
 218
 219 Clear multiple nodes values in one operation. Find or create a node matching SUB
 220 by interpreting SUB as a path expression relative to each node matching
 221 BASE. If SUB is '.', the nodes matching BASE will be modified.
 222
 223 =item B<ins> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
 224
 225 Insert a new node with label LABEL right before or after PATH into the
 226 tree. WHERE must be either 'before' or 'after'.
 227
 228 =item B<insert> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
 229
 230 Alias of B<ins>.
 231
 232 =item B<mv> E<lt>SRCE<gt> E<lt>DSTE<gt>
 233
 234 Move node SRC to DST. SRC must match exactly one node in the tree.  DST
 235 must either match exactly one node in the tree, or may not exist yet. If
 236 DST exists already, it and all its descendants are deleted. If DST does not
 237 exist yet, it and all its missing ancestors are created.
 238
 239 =item B<move> E<lt>SRCE<gt> E<lt>DSTE<gt>
 240
 241 Alias of B<mv>.
 242
 243 =item B<cp> E<lt>SRCE<gt> E<lt>DSTE<gt>
 244
 245 Copy node SRC to DST. SRC must match exactly one node in the tree.  DST
 246 must either match exactly one node in the tree, or may not exist yet. If
 247 DST exists already, it and all its descendants are deleted. If DST does not
 248 exist yet, it and all its missing ancestors are created.
 249
 250 =item B<copy> E<lt>SRCE<gt> E<lt>DSTE<gt>
 251
 252 Alias of B<cp>.
 253
 254 =item B<rename> E<lt>SRCE<gt> E<lt>LBLE<gt>
 255
 256 Rename the label of all nodes matching SRC to LBL.
 257
 258 =item B<rm> E<lt>PATHE<gt>
 259
 260 Delete PATH and all its children from the tree
 261
 262 =item B<set> E<lt>PATHE<gt> E<lt>VALUEE<gt>
 263
 264 Associate VALUE with PATH. If PATH is not in the tree yet,
 265 it and all its ancestors will be created.
 266
 267 =item B<setm> E<lt>BASEE<gt> E<lt>SUBE<gt> [E<lt>VALUEE<gt>]
 268
 269 Set multiple nodes in one operation.  Find or create a node matching SUB by
 270 interpreting SUB as a path expression relative to each node matching
 271 BASE. If SUB is '.', the nodes matching BASE will be modified.
 272
 273 =item B<touch> E<lt>PATHE<gt>
 274
 275 Create PATH with the value NULL if it is not in the tree yet.  All its
 276 ancestors will also be created.  These new tree entries will appear
 277 last amongst their siblings.
 278
 279 =back
 280
 281 =head2 PATH EXPRESSION COMMANDS
 282
 283 The following commands help when working with path expressions.
 284
 285 =over 4
 286
 287 =item B<defnode> E<lt>NAMEE<gt> E<lt>EXPRE<gt> [E<lt>VALUEE<gt>]
 288
 289 Define the variable NAME to the result of evaluating EXPR, which must be a
 290 nodeset. If no node matching EXPR exists yet, one is created and NAME will
 291 refer to it. If VALUE is given, this is the same as 'set EXPR VALUE'; if
 292 VALUE is not given, the node is created as if with 'clear EXPR' would and
 293 NAME refers to that node.
 294
 295 =item B<defvar> E<lt>NAMEE<gt> E<lt>EXPRE<gt>
 296
 297 Define the variable NAME to the result of evaluating EXPR. The variable
 298 can be used in path expressions as $NAME. Note that EXPR is evaluated when
 299 the variable is defined, not when it is used.
 300
 301 =back
 302
 303 =head1 ENVIRONMENT VARIABLES
 304
 305 =over 4
 306
 307 =item B<AUGEAS_ROOT>
 308
 309 The file system root, defaults to '/'. Can be overridden with
 310 the B<-r> command line option
 311
 312 =item B<AUGEAS_LENS_LIB>
 313
 314 Colon separated list of directories with lenses. Directories specified here
 315 are searched after any directories set with the B<-I> command line option,
 316 but before the default directories F</usr/share/augeas/lenses> and
 317 F</usr/share/augeas/lenses/dist>
 318
 319 =back
 320
 321 =head1 DIAGNOSTICS
 322
 323 Normally, exit status is 0. If one or more commands fail, the exit status
 324 is set to a non-zero value.
 325
 326 Note though that failure to load some of the files specified by transforms
 327 in C</augeas/load> is not considered a failure. If it is important to know
 328 that all files were loaded, you need to issue a C<match /augeas//error>
 329 after loading to find out details about what files could not be loaded and
 330 why.
 331
 332 =head1 EXAMPLES
 333
 334   # command line mode
 335   augtool print /files/etc/hosts/
 336
 337   # interactive mode
 338   augtool
 339   augtool> help
 340   augtool> print /files/etc/hosts/
 341
 342   # Print the third entry from the second AcceptEnv line
 343   augtool print '/files/etc/ssh/sshd_config/AcceptEnv[2]/3'
 344
 345   # Find the entry in inittab with action 'initdefault'
 346   augtool> match /files/etc/inittab/*/action initdefault
 347
 348   # Print the last alias for each entry in /etc/hosts
 349   augtool> print /files/etc/hosts/*/alias[last()]
 350
 351 =head1 FILES
 352
 353 Lenses and schema definitions in F</usr/share/augeas/lenses> and
 354 F</usr/share/augeas/lenses/dist>
 355
 356 =head1 AUTHOR
 357
 358   David Lutterkort <dlutter@redhat.com>
 359
 360 =head1 COPYRIGHT AND LICENSE
 361
 362 Copyright 2007-2012 Red Hat Inc.
 363
 364 Augeas (and augtool) are distributed under the GNU Lesser General Public
 365 License (LGPL)
 366
 367 =head1 SEE ALSO
 368
 369 B<Augeas> project homepage L<http://www.augeas.net/>
 370
 371 L<augparse>