man/augtool.1

   1 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "AUGTOOL 1"
 127 .TH AUGTOOL 1 "2011-12-01" "Augeas 0.9.0" "Augeas"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 augtool \- inspect and modify configuration files
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 augtool [\s-1OPTIONS\s0] [\s-1COMMAND\s0]
 137 .SH "DESCRIPTION"
 138 .IX Header "DESCRIPTION"
 139 Augeas is a configuration editing tool. It parses configuration files
 140 in their native formats and transforms them into a tree. Configuration
 141 changes are made by manipulating this tree and saving it back into
 142 native config files.
 143 .PP
 144 augtool provides a command line interface to the generated tree. \s-1COMMAND\s0
 145 can be a single command as described under \*(L"\s-1COMMANDS\s0\*(R". When called with
 146 no \s-1COMMAND\s0, it reads commands from standard input until an end-of-file is
 147 encountered.
 148 .SH "OPTIONS"
 149 .IX Header "OPTIONS"
 150 .IP "\fB\-c\fR, \fB\-\-typecheck\fR" 4
 151 .IX Item "-c, --typecheck"
 152 Typecheck lenses. This can be very slow, and is therefore not done by
 153 default, but is highly recommended during development.
 154 .IP "\fB\-b\fR, \fB\-\-backup\fR" 4
 155 .IX Item "-b, --backup"
 156 When files are changed, preserve the originals in a file with extension
 157 \&'.augsave'
 158 .IP "\fB\-n\fR, \fB\-\-new\fR" 4
 159 .IX Item "-n, --new"
 160 Save changes in files with extension '.augnew', do not modify the original
 161 files
 162 .IP "\fB\-r\fR, \fB\-\-root\fR=\fI\s-1ROOT\s0\fR" 4
 163 .IX Item "-r, --root=ROOT"
 164 Use directory \s-1ROOT\s0 as the root of the filesystem. Takes precedence over a
 165 root set with the \s-1AUGEAS_ROOT\s0 environment variable.
 166 .IP "\fB\-I\fR, \fB\-\-include\fR=\fI\s-1DIR\s0\fR" 4
 167 .IX Item "-I, --include=DIR"
 168 Add \s-1DIR\s0 to the module loadpath. Can be given multiple times. The
 169 directories set here are searched before any directories specified in the
 170 \&\s-1AUGEAS_LENS_LIB\s0 environment variable, and before the default directory
 171 \&\fI/usr/share/augeas/lenses\fR.
 172 .IP "\fB\-f\fR, \fB\-\-file\fR=\fI\s-1FILE\s0\fR" 4
 173 .IX Item "-f, --file=FILE"
 174 Read commands from \s-1FILE\s0.
 175 .IP "\fB\-i\fR, \fB\-\-interactive\fR" 4
 176 .IX Item "-i, --interactive"
 177 Read commands from the terminal. When combined with \fB\-f\fR or redirection of
 178 stdin, drop into an interactive session after executing the commands from
 179 the file.
 180 .IP "\fB\-e\fR" 4
 181 .IX Item "-e"
 182 When reading commands from a file via stdin, echo the commands before
 183 printing their output.
 184 .IP "\fB\-s\fR, \fB\-\-autosave\fR" 4
 185 .IX Item "-s, --autosave"
 186 Automatically save all changes at the end of the session.
 187 .IP "\fB\-S\fR, \fB\-\-nostdinc\fR" 4
 188 .IX Item "-S, --nostdinc"
 189 Do not search any of the default directories for modules. When this option
 190 is set, only directories specified explicitly with \fB\-I\fR or specified in
 191 \&\fB\s-1AUGEAS_LENS_LIB\s0\fR will be searched for modules.
 192 .IP "\fB\-L\fR, \fB\-\-noload\fR" 4
 193 .IX Item "-L, --noload"
 194 Do not load any files on startup. This is generally used to fine-tune which
 195 files to load by modifying the entries in \f(CW\*(C`/augeas/load\*(C'\fR and then issuing
 196 a \f(CW\*(C`load\*(C'\fR command.
 197 .IP "\fB\-A\fR, \fB\-\-noautoload\fR" 4
 198 .IX Item "-A, --noautoload"
 199 Do not load any lens modules, and therefore no files, on startup. This
 200 creates no entries under \f(CW\*(C`/augeas/load\*(C'\fR whatsoever; to read any files,
 201 they need to be set up manually and loading must be initiated with a
 202 \&\f(CW\*(C`load\*(C'\fR command. Using this option gives the fastest startup.
 203 .IP "\fB\-\-version\fR" 4
 204 .IX Item "--version"
 205 Print version information and exit. The version is also in the tree under
 206 \&\f(CW\*(C`/augeas/version\*(C'\fR.
 207 .SH "COMMANDS"
 208 .IX Header "COMMANDS"
 209 In interactive mode, commands and paths can be completed by pressing \f(CW\*(C`TAB\*(C'\fR.
 210 .PP
 211 The paths accepted as arguments by commands use a small subset of XPath
 212 path expressions. A path expression consists of a number of segments,
 213 separated by \f(CW\*(C`/\*(C'\fR. In each segment, the character \f(CW\*(C`*\*(C'\fR can be used to match
 214 every node regardless of its label. Sibling nodes with identical labels can
 215 be distinguished by appending \f(CW\*(C`[N]\*(C'\fR to their label to match the N\-th
 216 sibling with such a label. The last sibling with a specific label can be
 217 reached as \f(CW\*(C`[last()]\*(C'\fR. See \*(L"\s-1EXAMPLES\s0\*(R" for some examples of this.
 218 .IP "\fBquit\fR" 4
 219 .IX Item "quit"
 220 Exit the program
 221 .IP "\fBls\fR <\s-1PATH\s0>" 4
 222 .IX Item "ls <PATH>"
 223 List the direct children of \s-1PATH\s0
 224 .IP "\fBmatch\fR <\s-1PATTERN\s0> [<\s-1VALUE\s0>]" 4
 225 .IX Item "match <PATTERN> [<VALUE>]"
 226 Find all paths that match \s-1PATTERN\s0. If \s-1VALUE\s0 is given, only the matching
 227 paths whose value equals \s-1VALUE\s0 are printed
 228 .IP "\fBrm\fR <\s-1PATH\s0>" 4
 229 .IX Item "rm <PATH>"
 230 Delete \s-1PATH\s0 and all its children from the tree
 231 .IP "\fBmv\fR <\s-1SRC\s0> <\s-1DST\s0>" 4
 232 .IX Item "mv <SRC> <DST>"
 233 Move node \s-1SRC\s0 to \s-1DST\s0. \s-1SRC\s0 must match exactly one node in the tree.  \s-1DST\s0
 234 must either match exactly one node in the tree, or may not exist yet. If
 235 \&\s-1DST\s0 exists already, it and all its descendants are deleted. If \s-1DST\s0 does not
 236 exist yet, it and all its missing ancestors are created.
 237 .IP "\fBset\fR <\s-1PATH\s0> <\s-1VALUE\s0>" 4
 238 .IX Item "set <PATH> <VALUE>"
 239 Associate \s-1VALUE\s0 with \s-1PATH\s0. If \s-1PATH\s0 is not in the tree yet,
 240 it and all its ancestors will be created.
 241 .IP "\fBclear\fR <\s-1PATH\s0>" 4
 242 .IX Item "clear <PATH>"
 243 Set the value for \s-1PATH\s0 to \s-1NULL\s0. If \s-1PATH\s0 is not in the tree yet, it and all
 244 its ancestors will be created.
 245 .IP "\fBsetm\fR <\s-1BASE\s0> <\s-1SUB\s0> <\s-1VALUE\s0>" 4
 246 .IX Item "setm <BASE> <SUB> <VALUE>"
 247 Set multiple nodes in one operation.  Find or create a node matching \s-1SUB\s0 by
 248 interpreting \s-1SUB\s0 as a path expression relative to each node matching
 249 \&\s-1BASE\s0. If \s-1SUB\s0 is '.', the nodes matching \s-1BASE\s0 will be modified.
 250 .IP "\fBget\fR <\s-1PATH\s0>" 4
 251 .IX Item "get <PATH>"
 252 Print the value associated with \s-1PATH\s0
 253 .IP "\fBprint\fR \fI[<\s-1PATH\s0>]\fR" 4
 254 .IX Item "print [<PATH>]"
 255 Print entries in the tree. If \s-1PATH\s0 is given, printing starts there,
 256 otherwise the whole tree is printed
 257 .IP "\fBdump-xml\fR \fI[<\s-1PATH\s0>]\fR \fI[<\s-1FILENAME\s0>]\fR" 4
 258 .IX Item "dump-xml [<PATH>] [<FILENAME>]"
 259 Print entries in the tree as \s-1XML\s0. If \s-1PATH\s0 is given, printing starts there,
 260 otherwise the whole tree is printed. If \s-1FILENAME\s0 is given, the \s-1XML\s0 is saved
 261 to the given file.
 262 .IP "\fBins\fR \fI<\s-1LABEL\s0>\fR \fI<\s-1WHERE\s0>\fR \fI<\s-1PATH\s0>\fR" 4
 263 .IX Item "ins <LABEL> <WHERE> <PATH>"
 264 Insert a new node with label \s-1LABEL\s0 right before or after \s-1PATH\s0 into the
 265 tree. \s-1WHERE\s0 must be either 'before' or 'after'.
 266 .IP "\fBsave\fR" 4
 267 .IX Item "save"
 268 Save all pending changes to disk. Unless either the \fB\-b\fR or \fB\-n\fR
 269 command line options are given, files are changed in place.
 270 .IP "\fBload\fR" 4
 271 .IX Item "load"
 272 Load files according to the transforms in \f(CW\*(C`/augeas/load\*(C'\fR.
 273 .IP "\fBdefvar\fR <\s-1NAME\s0> <\s-1EXPR\s0>" 4
 274 .IX Item "defvar <NAME> <EXPR>"
 275 Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR\s0. The variable
 276 can be used in path expressions as \f(CW$NAME\fR. Note that \s-1EXPR\s0 is evaluated when
 277 the variable is defined, not when it is used.
 278 .IP "\fBdefnode\fR <\s-1NAME\s0> <\s-1EXPR\s0> [<\s-1VALUE\s0>]" 4
 279 .IX Item "defnode <NAME> <EXPR> [<VALUE>]"
 280 Define the variable \s-1NAME\s0 to the result of evaluating \s-1EXPR\s0, which must be a
 281 nodeset. If no node matching \s-1EXPR\s0 exists yet, one is created and \s-1NAME\s0 will
 282 refer to it. If \s-1VALUE\s0 is given, this is the same as 'set \s-1EXPR\s0 \s-1VALUE\s0'; if
 283 \&\s-1VALUE\s0 is not given, the node is created as if with 'clear \s-1EXPR\s0' would and
 284 \&\s-1NAME\s0 refers to that node.
 285 .IP "\fBspan\fR <\s-1PATH\s0>" 4
 286 .IX Item "span <PATH>"
 287 Print the name of the file from which the node \s-1PATH\s0 was generated, as well
 288 as information about the positions in the file corresponding to the label,
 289 the value, and the entire node. \s-1PATH\s0 must match exactly one node.
 290 .Sp
 291 You need to run 'set /augeas/span enable' prior to loading files to enable
 292 recording of span information. It is disabled by default.
 293 .IP "\fBhelp\fR" 4
 294 .IX Item "help"
 295 Print this help text
 296 .SH "ENVIRONMENT VARIABLES"
 297 .IX Header "ENVIRONMENT VARIABLES"
 298 .IP "\fB\s-1AUGEAS_ROOT\s0\fR" 4
 299 .IX Item "AUGEAS_ROOT"
 300 The file system root, defaults to '/'. Can be overridden with
 301 the \fB\-r\fR command line option
 302 .IP "\fB\s-1AUGEAS_LENS_LIB\s0\fR" 4
 303 .IX Item "AUGEAS_LENS_LIB"
 304 Colon separated list of directories with lenses. Directories specified here
 305 are searched after any directories set with the \fB\-I\fR command line option,
 306 but before the default directory \fI/usr/share/augeas/lenses\fR
 307 .SH "DIAGNOSTICS"
 308 .IX Header "DIAGNOSTICS"
 309 Normally, exit status is 0. If one or more commands fail, the exit status
 310 is set to a non-zero value.
 311 .PP
 312 Note though that failure to load some of the files specified by transforms
 313 in \f(CW\*(C`/augeas/load\*(C'\fR is not considered a failure. If it is important to know
 314 that all files were loaded, you need to issue a \f(CW\*(C`match /augeas//error\*(C'\fR
 315 after loading to find out details about what files could not be loaded and
 316 why.
 317 .SH "EXAMPLES"
 318 .IX Header "EXAMPLES"
 319 .Vb 2
 320 \&  # command line mode
 321 \&  augtool print /files/etc/hosts/
 322 \&
 323 \&  # interactive mode
 324 \&  augtool
 325 \&  augtool> help
 326 \&  augtool> print /files/etc/hosts/
 327 \&
 328 \&  # Print the third entry from the second AcceptEnv line
 329 \&  augtool print \*(Aq/files/etc/ssh/sshd_config/AcceptEnv[2]/3\*(Aq
 330 \&
 331 \&  # Find the entry in inittab with action \*(Aqinitdefault\*(Aq
 332 \&  augtool> match /files/etc/inittab/*/action initdefault
 333 \&
 334 \&  # Print the last alias for each entry in /etc/hosts
 335 \&  augtool> print /files/etc/hosts/*/alias[last()]
 336 .Ve
 337 .SH "FILES"
 338 .IX Header "FILES"
 339 Lenses and schema definitions in \fI/usr/share/augeas/lenses\fR
 340 .SH "AUTHOR"
 341 .IX Header "AUTHOR"
 342 .Vb 1
 343 \&  David Lutterkort <dlutter@redhat.com>
 344 .Ve
 345 .SH "COPYRIGHT AND LICENSE"
 346 .IX Header "COPYRIGHT AND LICENSE"
 347 Copyright 2007\-2011 Red Hat Inc.
 348 .PP
 349 Augeas (and augtool) are distributed under the \s-1GNU\s0 Lesser General Public
 350 License (\s-1LGPL\s0)
 351 .SH "SEE ALSO"
 352 .IX Header "SEE ALSO"
 353 \&\fBAugeas\fR project homepage <http://www.augeas.net/>
 354 .PP
 355 augparse