AUGPRINT(1) Augeas AUGPRINT(1) NAME augprint - create an idempotent augtool script for a given file SYNOPSIS augprint [--pretty|-p] [--regexp[=n]|-r[n]] [--noseq|-s] [--verbose|-v] [--lens name|-l name] [--target /target|-t /target] FILE DESCRIPTION augprint creates an augtool script for a given FILE consisting primarily of "set" commands. The resulting augtool script is designed to be idempotent, and will not re- sult in any changes when applied to the original file. augprint replaces each numbered location in the tree with a path-expression that uniquely identifies the position using the values within that posi- tion. This makes the path-expression independant of the position-number, and thereby applicable to files which in which the same data may exist at an alternate position-number See "Examples" for sample output Regexp output By default augprint produces path-expressions made up of simple equality "=" comparisions set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1' The option --regexp changes the output to produce regular expression com- parisions set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\.0\\..*')]/ipaddr '127.0.0.1' The minimum length N of the regular expression can be specified using "--regexp=N" augprint will choose a longer regular expression than N if multiple values would match using the N character regular expression. Limitations Append-only The output is based primarily on set operations. The set operation can only: a) change an existing value in-situ b) append a new value after the last position in the group This means that when an entry is re-created, it may not be in the same po- sition as originally intended. ie if the entry for 192.0.2.3 does not al- ready exist, it will be created as the last entry in /etc/hosts Often, such out-of-sequence entries will not matter to the resulting con- figuration file. If it does matter, further manual editing of the "aug- tool" script will be required. Repeated Values augprint is not always successful in finding a path-expression which is unique to a position. In this case augprint appends a position to an ex- pression which is not unique This occurs in particular if there are repeated values within the file. For an /etc/hosts file of #------ 192.0.2.3 defaultdns #------ augprint would produce the output set /files/etc/hosts/#comment[.='--------'][1] '--------' set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/ipaddr '192.0.2.3' set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/canonical 'defaultdns' set /files/etc/hosts/#comment[.='--------'][2] '--------' Notice how "#comment" paths have "[1]" and "[2]" appended respectively to the "[expr]" Other paths which do have unique path-expressions are not directly affected OPTIONS -v, --verbose Include the original numbered paths as comments in the output -p, --pretty Create more readable output by adding spaces and empty lines -r, -rN, --regexp, --regexp=N Generate regular expressions to match values, using a minumum length of N characters from the value N can be omitted and defaults to 8 -l, --lens=LENS Use LENS for the given file; without this option, augprint uses the de- fault lens for the file -t targetfile, --target=targetfile Generate the script for the FILE specified as if its path was really targetfile This will apply the lens corresponding to targetfile to FILE and modi- fying the resulting path-expressions of FILE to correspond to target- file targetfile must be the full path name, starting with a '/' See "Examples" for how --target can be used in practice -s, --noseq Do not use "seq::*" in the output, use "*" instead. For example set /files/etc/hosts/*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1' IMPORTANT: The resulting output will no longer create a new entry for 127.0.0.1 if none already exists. The "--noseq" option exists so that the resulting paths can be used with augeas versions prior to 1.13.0 (subject to this limitation) EXAMPLES These examples use the following /etc/hosts file as the FILE 127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 192.0.2.3 dns-a 192.0.2.4 dns-b The output from "augtool 'print /files/etc/hosts'" would be /files/etc/hosts /files/etc/hosts/1 /files/etc/hosts/1/ipaddr = "127.0.0.1" /files/etc/hosts/1/canonical = "localhost" /files/etc/hosts/1/alias[1] = "localhost.localdomain" /files/etc/hosts/1/alias[2] = "localhost4" /files/etc/hosts/1/alias[3] = "localhost4.localdomain4" /files/etc/hosts/2 /files/etc/hosts/2/ipaddr = "192.0.2.3" /files/etc/hosts/2/canonical = "dns-a" /files/etc/hosts/3 /files/etc/hosts/3/ipaddr = "192.0.2.4" /files/etc/hosts/3/canonical = "dns-b" Default output "augprint /etc/hosts" set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1' set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/canonical 'localhost' set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost.localdomain'] 'localhost.localdomain' set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost4'] 'localhost4' set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost4.localdomain4'] 'localhost4.localdomain4' set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/ipaddr '192.0.2.3' set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/canonical 'dns-a' set /files/etc/hosts/seq::*[ipaddr='192.0.2.4']/ipaddr '192.0.2.4' set /files/etc/hosts/seq::*[ipaddr='192.0.2.4']/canonical 'dns-b' Verbose output "augprint --verbose /etc/hosts" # /files/etc/hosts # /files/etc/hosts/1 # /files/etc/hosts/1/ipaddr '127.0.0.1' set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1' # /files/etc/hosts/1/canonical 'localhost' set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/canonical 'localhost' # /files/etc/hosts/1/alias[1] 'localhost.localdomain' set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost.localdomain'] 'localhost.localdomain' ... Rexexp output "augprint --regexp=4 /etc/hosts" set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/ipaddr '127.0.0.1' set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/canonical 'localhost' set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost\\..*')] 'localhost.localdomain' set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost4')] 'localhost4' set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost4\\..*')] 'localhost4.localdomain4' set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.3')]/ipaddr '192.0.2.3' set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.3')]/canonical 'dns-a' set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.4')]/ipaddr '192.0.2.4' set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.4')]/canonical 'dns-b' Note that although a minimum length of 4 has been specified, augprint will choose longer regular expressions as needed to ensure a unique match. Using --lens If a file is not assocatiated with a lens by default, --lens lensname can be used to specify a lens. When --lens is specified, the output is prefixed with suitable "transform" and "load-file" statements, as required to complete the augtool script, and a setm statement to exclude other autoloaded lenses. "augprint --lens shellvars /etc/skel/.bashrc" setm /augeas/load/*[incl='/etc/skel/.bashrc' and label() != 'shellvars']/excl '/etc/skel/.bashrc' transform shellvars incl /etc/skel/.bashrc load-file /etc/skel/.bashrc set /files/etc/skel/.bashrc/#comment[.='.bashrc'] '.bashrc' set /files/etc/skel/.bashrc/#comment[.='Source global definitions'] 'Source global definitions' set /files/etc/skel/.bashrc/@if[.='[ -f /etc/bashrc ]'] '[ -f /etc/bashrc ]' set /files/etc/skel/.bashrc/@if[.='[ -f /etc/bashrc ]']/.source '/etc/bashrc' set /files/etc/skel/.bashrc/#comment[.='User specific environment'] 'User specific environment' ... The lenses "simplelines" "shellvars" are most commonly useful as lenses for files that do not have a specific lens Using --target In order to prepare an augtool script intended for a given file, it may be desired to copy the file to another location, rather than editting the original file. The option --target simplifies this process. a) copy /etc/hosts to a new location cp /etc/hosts ~ b) edit ~/hosts to suit echo '192.0.2.7 defaultdns' >> ~/hosts c) Run "augprint" as follows augprint --target /etc/hosts ~/hosts d) Copy the relevant part of the output to an augtool script or other Augeas client set /files/etc/hosts/seq::*[ipaddr='192.0.2.7']/ipaddr '192.0.2.7' set /files/etc/hosts/seq::*[ipaddr='192.0.2.7']/canonical 'defaultdns' Notice that "augprint" has generated paths corresponding to --target (/etc/hosts) instead of the FILE argument (~/hosts) ENVIRONMENT VARIABLES AUGEAS_ROOT The effective file system root, defaults to '/'. AUGEAS_LENS_LIB Colon separated list of directories with lenses. Directories specified here are searched before the default directories /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist EXIT STATUS The exit status is 0 when the command was successful and 1 if any error oc- curred. FILES Lenses and schema definitions in /usr/share/augeas/lenses and /usr/share/augeas/lenses/dist AUTHOR George Hansper <george@hansper.id.au> COPYRIGHT AND LICENSE Copyright 2022 George Hansper Augeas (and augprint) are distributed under the GNU Lesser General Public License (LGPL), version 2.1 SEE ALSO augtool(1) Augeas project homepage <https://www.augeas.net/> Augeas path expressions <https://github.com/her- cules-team/augeas/wiki/Path-expressions> Augeas 1.14.0 2022-12-06 AUGPRINT(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | FILES | AUTHOR | COPYRIGHT AND LICENSE | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=augprint&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>