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 directory
  50 F</usr/share/augeas/lenses>.
  51
  52 =item B<-f>, B<--file>=I<FILE>
  53
  54 Read commands from FILE.
  55
  56 =item B<-i>, B<--interactive>
  57
  58 Read commands from the terminal. When combined with B<-f> or redirection of
  59 stdin, drop into an interactive session after executing the commands from
  60 the file.
  61
  62 =item B<-e>
  63
  64 When reading commands from a file via stdin, echo the commands before
  65 printing their output.
  66
  67 =item B<-s>, B<--autosave>
  68
  69 Automatically save all changes at the end of the session.
  70
  71 =item B<-S>, B<--nostdinc>
  72
  73 Do not search any of the default directories for modules. When this option
  74 is set, only directories specified explicitly with B<-I> or specified in
  75 B<AUGEAS_LENS_LIB> will be searched for modules.
  76
  77 =item B<-L>, B<--noload>
  78
  79 Do not load any files on startup. This is generally used to fine-tune which
  80 files to load by modifying the entries in C</augeas/load> and then issuing
  81 a C<load> command.
  82
  83 =item B<-A>, B<--noautoload>
  84
  85 Do not load any lens modules, and therefore no files, on startup. This
  86 creates no entries under C</augeas/load> whatsoever; to read any files,
  87 they need to be set up manually and loading must be initiated with a
  88 C<load> command. Using this option gives the fastest startup.
  89
  90 =item B<--version>
  91
  92 Print version information and exit. The version is also in the tree under
  93 C</augeas/version>.
  94
  95 =back
  96
  97 =head1 COMMANDS
  98
  99 In interactive mode, commands and paths can be completed by pressing C<TAB>.
 100
 101 The paths accepted as arguments by commands use a small subset of XPath
 102 path expressions. A path expression consists of a number of segments,
 103 separated by C</>. In each segment, the character C<*> can be used to match
 104 every node regardless of its label. Sibling nodes with identical labels can
 105 be distinguished by appending C<[N]> to their label to match the N-th
 106 sibling with such a label. The last sibling with a specific label can be
 107 reached as C<[last()]>. See L</EXAMPLES> for some examples of this.
 108
 109 =over 4
 110
 111 =item B<quit>
 112
 113 Exit the program
 114
 115 =item B<ls> E<lt>PATHE<gt>
 116
 117 List the direct children of PATH
 118
 119 =item B<match> E<lt>PATTERNE<gt> [E<lt>VALUEE<gt>]
 120
 121 Find all paths that match PATTERN. If VALUE is given, only the matching
 122 paths whose value equals VALUE are printed
 123
 124 =item B<rm> E<lt>PATHE<gt>
 125
 126 Delete PATH and all its children from the tree
 127
 128 =item B<mv> E<lt>SRCE<gt> E<lt>DSTE<gt>
 129
 130 Move node SRC to DST. SRC must match exactly one node in the tree.  DST
 131 must either match exactly one node in the tree, or may not exist yet. If
 132 DST exists already, it and all its descendants are deleted. If DST does not
 133 exist yet, it and all its missing ancestors are created.
 134
 135 =item B<set> E<lt>PATHE<gt> E<lt>VALUEE<gt>
 136
 137 Associate VALUE with PATH. If PATH is not in the tree yet,
 138 it and all its ancestors will be created.
 139
 140 =item B<clear> E<lt>PATHE<gt>
 141
 142 Set the value for PATH to NULL. If PATH is not in the tree yet, it and all
 143 its ancestors will be created.
 144
 145 =item B<setm> E<lt>BASEE<gt> E<lt>SUBE<gt> E<lt>VALUEE<gt>
 146
 147 Set multiple nodes in one operation.  Find or create a node matching SUB by
 148 interpreting SUB as a path expression relative to each node matching
 149 BASE. If SUB is '.', the nodes matching BASE will be modified.
 150
 151 =item B<get> E<lt>PATHE<gt>
 152
 153 Print the value associated with PATH
 154
 155 =item B<print> I<[E<lt>PATHE<gt>]>
 156
 157 Print entries in the tree. If PATH is given, printing starts there,
 158 otherwise the whole tree is printed
 159
 160 =item B<dump-xml> I<[E<lt>PATHE<gt>]> I<[E<lt>FILENAMEE<gt>]>
 161
 162 Print entries in the tree as XML. If PATH is given, printing starts there,
 163 otherwise the whole tree is printed. If FILENAME is given, the XML is saved
 164 to the given file.
 165
 166 =item B<ins> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
 167
 168 Insert a new node with label LABEL right before or after PATH into the
 169 tree. WHERE must be either 'before' or 'after'.
 170
 171 =item B<save>
 172
 173 Save all pending changes to disk. Unless either the B<-b> or B<-n>
 174 command line options are given, files are changed in place.
 175
 176 =item B<load>
 177
 178 Load files according to the transforms in C</augeas/load>.
 179
 180 =item B<defvar> E<lt>NAMEE<gt> E<lt>EXPRE<gt>
 181
 182 Define the variable NAME to the result of evaluating EXPR. The variable
 183 can be used in path expressions as $NAME. Note that EXPR is evaluated when
 184 the variable is defined, not when it is used.
 185
 186 =item B<defnode> E<lt>NAMEE<gt> E<lt>EXPRE<gt> [E<lt>VALUEE<gt>]
 187
 188 Define the variable NAME to the result of evaluating EXPR, which must be a
 189 nodeset. If no node matching EXPR exists yet, one is created and NAME will
 190 refer to it. If VALUE is given, this is the same as 'set EXPR VALUE'; if
 191 VALUE is not given, the node is created as if with 'clear EXPR' would and
 192 NAME refers to that node.
 193
 194 =item B<span> E<lt>PATHE<gt>
 195
 196 Print the name of the file from which the node PATH was generated, as well
 197 as information about the positions in the file corresponding to the label,
 198 the value, and the entire node. PATH must match exactly one node.
 199
 200 You need to run 'set /augeas/span enable' prior to loading files to enable
 201 recording of span information. It is disabled by default.
 202
 203 =item B<help>
 204
 205 Print this help text
 206
 207 =back
 208
 209 =head1 ENVIRONMENT VARIABLES
 210
 211 =over 4
 212
 213 =item B<AUGEAS_ROOT>
 214
 215 The file system root, defaults to '/'. Can be overridden with
 216 the B<-r> command line option
 217
 218 =item B<AUGEAS_LENS_LIB>
 219
 220 Colon separated list of directories with lenses. Directories specified here
 221 are searched after any directories set with the B<-I> command line option,
 222 but before the default directory F</usr/share/augeas/lenses>
 223
 224 =back
 225
 226 =head1 DIAGNOSTICS
 227
 228 Normally, exit status is 0. If one or more commands fail, the exit status
 229 is set to a non-zero value.
 230
 231 Note though that failure to load some of the files specified by transforms
 232 in C</augeas/load> is not considered a failure. If it is important to know
 233 that all files were loaded, you need to issue a C<match /augeas//error>
 234 after loading to find out details about what files could not be loaded and
 235 why.
 236
 237 =head1 EXAMPLES
 238
 239   # command line mode
 240   augtool print /files/etc/hosts/
 241
 242   # interactive mode
 243   augtool
 244   augtool> help
 245   augtool> print /files/etc/hosts/
 246
 247   # Print the third entry from the second AcceptEnv line
 248   augtool print '/files/etc/ssh/sshd_config/AcceptEnv[2]/3'
 249
 250   # Find the entry in inittab with action 'initdefault'
 251   augtool> match /files/etc/inittab/*/action initdefault
 252
 253   # Print the last alias for each entry in /etc/hosts
 254   augtool> print /files/etc/hosts/*/alias[last()]
 255
 256 =head1 FILES
 257
 258 Lenses and schema definitions in F</usr/share/augeas/lenses>
 259
 260 =head1 AUTHOR
 261
 262   David Lutterkort <dlutter@redhat.com>
 263
 264 =head1 COPYRIGHT AND LICENSE
 265
 266 Copyright 2007-2011 Red Hat Inc.
 267
 268 Augeas (and augtool) are distributed under the GNU Lesser General Public
 269 License (LGPL)
 270
 271 =head1 SEE ALSO
 272
 273 B<Augeas> project homepage L<http://www.augeas.net/>
 274
 275 L<augparse>