.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Config::Model::Backend::Augeas 3pm" .TH Config::Model::Backend::Augeas 3pm "2022-01-07" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Config::Model::Backend::Augeas \- Read and write config data through Augeas .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& # model specification with augeas backend \& { \& config_class_name => \*(AqOpenSsh::Sshd\*(Aq, \& \& read_config => { \& backend => \*(Aqaugeas\*(Aq , \& file => \*(Aq/etc/ssh/sshd_config\*(Aq, \& # declare "seq" Augeas elements \& sequential_lens => [/AcceptEnv AllowGroups [etc]/], \& }, \& \& # config is written back using read_config specifications \& \& element => ... \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class provides a way to load or store configuration data through Config::Augeas. This way, the structure and comments of the original configuration file are preserved. .PP To use Augeas as a backend, you must specify the following \&\f(CW\*(C`read_config\*(C'\fR parameters: .IP "backend" 4 .IX Item "backend" Use \f(CW\*(C`augeas\*(C'\fR (or \f(CW\*(C`Augeas\*(C'\fR)in this case. .IP "save" 4 .IX Item "save" Either \f(CW\*(C`backup\*(C'\fR or \f(CW\*(C`newfile\*(C'\fR. See \*(L"Constructor\*(R" in Config::Augeas for details. .IP "file" 4 .IX Item "file" Name of the configuration file. .IP "sequential_lens" 4 .IX Item "sequential_lens" This one is tricky. Set to one when new Augeas list or hash node must be created for each new list or hash element. See \*(L"Sequential lens\*(R" for details. .PP For instance: .PP .Vb 7 \& read_config => { \& backend => \*(Aqaugeas\*(Aq , \& save => \*(Aqbackup\*(Aq, \& file => \*(Aq/etc/ssh/sshd_config\*(Aq, \& # declare "seq" Augeas elements \& sequential_lens => [/AcceptEnv AllowGroups/], \& }, .Ve .SS "Sequential lens" .IX Subsection "Sequential lens" Some configuration files feature data that must be written as list or as hash. Depending on the syntax, Augeas list or hash lenses can be written so that new \*(L"container\*(R" nodes are required for each new element. .PP For instance, \f(CW\*(C`HostKey\*(C'\fR lines can be repeated several times in \&\f(CW\*(C`sshd_config\*(C'\fR. Since Augeas must keep track of these several lines, Augeas tree will be written like: .PP .Vb 3 \& /files/etc/ssh/sshd_config/HostKey[1] \& /files/etc/ssh/sshd_config/HostKey[2] \& /files/etc/ssh/sshd_config/HostKey[3] .Ve .PP and not: .PP .Vb 3 \& /files/etc/ssh/sshd_config/HostKey/1 \& /files/etc/ssh/sshd_config/HostKey/2 \& /files/etc/ssh/sshd_config/HostKey/3 .Ve .PP The \f(CW\*(C`HostKey\*(C'\fR node is created several times. A new hostkey must be added with the following syntax: .PP .Vb 1 \& /files/etc/ssh/sshd_config/HostKey[4] .Ve .PP and not: .PP .Vb 1 \& /files/etc/ssh/sshd_config/HostKey/4 .Ve .PP So the \f(CW\*(C`HostKey\*(C'\fR lens is sequential. .PP The situation is more complex when syntax allow repeated values on several lines. Like: .PP .Vb 2 \& AcceptEnv LC_PAPER LC_NAME LC_ADDRESS \& AcceptEnv LC_IDENTIFICATION LC_ALL .Ve .PP Augeas will have this tree: .PP .Vb 5 \& /files/etc/ssh/sshd_config/AcceptEnv[1]/1 \& /files/etc/ssh/sshd_config/AcceptEnv[1]/2 \& /files/etc/ssh/sshd_config/AcceptEnv[1]/3 \& /files/etc/ssh/sshd_config/AcceptEnv[2]/4 \& /files/etc/ssh/sshd_config/AcceptEnv[2]/5 .Ve .PP Note that the first index between square brackets keeps track of how the \f(CW\*(C`AcceptEnv\*(C'\fR items are grouped, but the \fIreal\fR list index is after the slash. .PP Augeas does not require new elements to create \f(CW\*(C`AcceptEnv[3]\*(C'\fR. A new element can be added as : .PP .Vb 1 \& /files/etc/ssh/sshd_config/AcceptEnv[2]/6 .Ve .PP So this lens is not sequential. .PP The same kind of trouble occurs with hash elements. Some hashes tree are like: .PP .Vb 2 \& /files/etc/foo/my_hash/my_key1 \& /files/etc/foo/my_hash/my_key2 .Ve .PP Others are like: .PP .Vb 2 \& /files/etc/foo/my_hash[1]/my_key1 \& /files/etc/foo/my_hash[2]/my_key2 .Ve .PP Note that a list-like index is used with the hash key. .PP This also depends on the syntax of the configuration file. For instance, \f(CW\*(C`Subsystem\*(C'\fR in \f(CW\*(C`sshd_config\*(C'\fR can be : .PP .Vb 3 \& Subsystem sftp /usr/lib/openssh/sftp\-server \& Subsystem fooftp /usr/lib/openssh/fooftp\-server \& Subsystem barftp /usr/lib/openssh/barftp\-server .Ve .PP This (unvalid) sshd configuration is represented by: .PP .Vb 3 \& /files/etc/ssh/sshd_config/Subsystem[1]/sftp \& /files/etc/ssh/sshd_config/Subsystem[2]/fooftp \& /files/etc/ssh/sshd_config/Subsystem[3]/barftp .Ve .PP Any new Subsystem must be added with: .PP .Vb 1 \& /files/etc/ssh/sshd_config/Subsystem[4]/bazftp .Ve .PP In this case, the hash is also sequential. .PP For these examples, the augeas backend declaration must feature: .PP .Vb 1 \& sequential_lens => [qw/HostKey Subsystem/], .Ve .SS "Augeas backend limitation" .IX Subsection "Augeas backend limitation" The structure and element names of the Config::Model tree must match the structure defined in Augeas lenses. I.e. the order of the element declared in Config::Model must match the order required by Augeas lenses. .PP Sometimes, the structure of a file loaded by Augeas starts directly with a list of items. For instance \f(CW\*(C`/etc/hosts\*(C'\fR structure starts with a list of lines that specify hosts and \s-1IP\s0 addresses. The \f(CW\*(C`set_in\*(C'\fR parameter specifies an element name in Config::Model root class that will hold the configuration data retrieved by Augeas. .SH "Log and trace" .IX Header "Log and trace" This module use Log::Log4perl to log debug and info trace with \&\f(CW\*(C`Data::Read\*(C'\fR and \f(CW\*(C`Data::Write\*(C'\fR categories. .SH "CAVEATS" .IX Header "CAVEATS" .IP "\(bu" 4 Augeas \f(CW\*(C`#comment\*(C'\fR nodes are ignored .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 http://augeas.net/ : Augeas project page .IP "\(bu" 4 config-model wiki: .IP "\(bu" 4 Blogs about this project: .IP "\(bu" 4 Augeas mailing list: http://augeas.net/developers.html .SH "AUTHOR" .IX Header "AUTHOR" Dominique Dumont, .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2008\-2010 by Dominique Dumont .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the \s-1LGPL\s0 terms.