www.delorie.com/gnu/docs/cfengine/cfengine-Reference_91.html   search  
 
Buy GNU books!


GNU cfengine

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.15 editfiles

Performs ascii (line-based) editing on text-files or limited binary editing of files. If editing a file which has hard links to it, be aware that editing the file will destroy the hard link references. This is also the case with shell commands. You should avoid hard links whenever possible. The form of an editing command is editfiles can also search directories recursively through directories and edit all files matching a pattern, using Include, Exclude, and Ignore (see Recursive File Sweeps in the tutorial).

 
editfiles:

   class::

      { file-to-be-edited

      action "quoted-string..."
      }

      { directory-to-be-edited

      Recurse "inf"
      Filter  "filteralias"
      Include ".cshrc"
      Ignore  "bin"
      Ignore  ".netscape"
      action "quoted-string..."
      }

Here are some examples:

 
editfiles:

   sun4::

      { /etc/netmasks

      DeleteLinesContaining "255.255.254.0"
      AppendIfNoSuchLine "128.39  255.255.255.0"
      }

   PrintServers::
      { /etc/hosts.lpd

      AppendIfNoSuchLine "tor"
      AppendIfNoSuchLine "odin"
      AppendIfNoSuchLine "borg"
      }

The first of these affects the file `/etc/netmasks' on all SunOS 4 systems, deleting any lines containing the string "255.255.254.0" and Appending a single line to the file containing "128.39 255.255.255.0" if none exists already. The second affects only hosts in the class `PrintServers' and adds the names of three hosts: tor, odin and borg to the file `/etc/hosts.lpd' which specifies that they are allowed to connect to the printer services on any host in the class `PrintServers'.

Note that single or double quotes may be used to enclose strings in cfengine. If you use single quotes, your strings may contain double quotes and vice-versa. Otherwise a double quoted string may not currently contain double quotes and likewise for single quoted strings.

As of version 1.3.0, you can use the `home' directive in edit filenames, enabling you to edit files for every user on the system, provided they exist. For example, to edit every user's login files, you would write

 
  { home/.cshrc

   AppendIfNoSuchLine "setenv PRINTER default-printer"
   AppendIfNoSuchLine "set path = ( $path /new/directory )"
  }

If a user does not possess the named file, cfengine just skips that user. A new file is not created.

The meanings of the file-editing actions should be self-explanatory. Commands containing the word 'comment' are used to `comment out' certain lines in a file rather than deleting them. Hash implies a shell comment of the type

 
# comment

Slash implies a comment of the C++ type:

 
// comment

Percent implies a comment of the type:

 
% comment

More general comment types may be defined using the SetCommentStart, SetCommentEnd and CommentLinesMatching, CommentLinesStarting functions.

A special group of editing commands is based on the GNU Regular Expression package. These use GNU regular expressions to search line by line through text and perform various editing functions. Some of these commands are based on the concept of a file pointer. The pointer starts at line one of the file and can be reset by 'locating' a certain line, or by using the reset-pointer commands. The current position of the pointer is used by commands such as InsertLine to allow a flexible way of editing the middle of files.

A simple decision mechanism is incorporated to allow certain editing actions to be excluded. For instance, to insert a number of lines in a file once only, you could write:

 
   { file

    LocateLineMatching "insert point..."
    IncrementPointer   "1"

    BeginGroupIfNoMatch "# cfengine - 2/Jan/95"
      IncremenetPointer "-1"
      InsertLine "# cfengine - 2/Jan/95"
      InsertLine "/local/bin/start-xdm"

    EndGroup
   }

Since the first inserted line matches the predicate on subsequent calls, the grouped lines will only be carried out once.

The full list of editing actions is given below in alphabetical order. Note that some commands refer to regular expressions and some refer to 'literal strings' (i.e. any string which is not a regular expression). Variable substitution is performed on all strings. Be aware that symbols such as `.', `*' and so on are meta-characters in regular expressions and a backslash must be used to make them literal. The regular expression matching functions are POSIX extended regular expressions. @xref{Regular expressions,Regular expressions,Regular expressions,cfengine-Tutorial}.

AbortAtLineMatching quoted-regex
This command sets the value of a regular expression. In all editing operations (except FixEndOfLine and GotoLastLine) which involve multiple replacements and searches, this expression marks a boundary beyond which cfengine will cease to look any further. In other words, if cfengine encounters a line matching this regular expression, it aborts the current action. BE CAREFUL with this feature: once set, the string remains set for the remainder of the current file. It might therefore interact in unsuspected ways with other search parameters. Editing actions are always aborted as soon as the abort expression is matched. Use UnsetAbort to unset the feature.

Append quoted-string
Add a line containing the quoted string to the end of the file. This should be used in conjunction with the decision structures BeginGroupIfNoLineMatching and BreakIfLineMatches.

AppendIfNoSuchLine quoted-string
Add a line containing the quoted string to the end of the file if the file doesn't contain the exact line already.

AppendIfNoLineMatching quoted-regex
A new version of the older AppendIfNoSuchLine which uses a regular expression instead of a literal string. The line which gets appended must be set previously using SetLine.

AppendToLineIfNotContains quoted-string
This commands looks for an exact match of the quoted string in the current line. If the quoted string is not contained in the line, it is appended. This may be used for adding entries to a list.

AutoCreate
If this command is listed anywhere in the file action list, cfengine will create the named file if it doesn't exist. Normally cfengine issues an error if the named file does not exist, but if this is set, notification of the file's absence is only in verbose output. New files are created with mode 644 (see also Umask), read access for everyone and write access for the cfengine user (normally root). Note that if you set this, BeginGroupIfFileIsNewer will always be true.

AutomountDirectResources quoted-string
This command is designed to assist with automounter configuration for users wishing to use the automounter for NFS filesystems, but still use the cfengine mount model. Applied to the current file, it is equivalent to saying: for each of the mountable resources in the list See section 3.26 mountables, append if not found a line for a direct automount map command, to the current file. The string which follows can be used to specify any special mount options e.g. "-nosuid" for non setuid mounting (of all the mountables). Note that this is added to the current file and not to a file named `/etc/auto_direct'.

Backup quoted-string
Set to true or false, on or off to set inform level for this file. Default is on.

BeginGroupIfDefined quoted-string
The lines following, up to the first EndGroup are executed if the quoted class is defined.

BeginGroupIfNotDefined quoted-string
The lines following, up to the first EndGroup are executed if the quoted class is not defined.

BeginGroupIfFileExists quoted-string
The lines following, up to the first EndGroup are executed if the quoted filename exists (can be statted). Files which are not readable by the running process are for all intents and purposes non-existent.

BeginGroupIfFileIsNewer quoted-string
The lines following, up to the first EndGroup are executed if the quoted filename is newer than the file being edited.

BeginGroupIfNoLineContaining quoted-string
The lines following, up to the first EndGroup are executed if the quoted string does not appear in any line in the file.

BeginGroupIfNoLineMatching quoted-regex
The lines following, up to the first EndGroup are executed if the quoted regular expression does not match any line in the file.

BeginGroupIfNoMatch quoted-regex
The lines following, up to the first EndGroup are executed if the quoted regular expression does not match the current line.

BeginGroupIfNoSuchLine quoted-string
The lines following, up to the first EndGroup are executed if the quoted literal string does not match any line in the file.

BreakIfLineMatches quoted-regex
Terminates further editing of the current file if the current line matches the quoted regular expression.

CatchAbort
Edit actions which abort on failure (such as LocateLineMatching) will jump to the first instance of this marker instead of completely aborting an edit if this keyword occurs in an editing script. You can catch the exceptions thrown by the following commands: CommentNLines,CommentToLineMatching,DeleteNLines,DeleteToLineMatching, HashCommentToLineMatching,IncrementPointer, LocateLineMatching,PercentCommentToLineMatching, RunScriptIf(No)LineMatching,UnCommentNLines.

CommentLinesMatching quoted-regex
Use the current value of the comment delimiters set using SetCommentStart and SetCommentEnd to comment out lines matching the given regular expression in quotes.

CommentLinesStarting quoted-string
Use the current value of the comment delimiters set using SetCommentStart and SetCommentEnd to comment out lines starting with the quoted literal string.

CommentNLines quoted-string
Comments up to N lines from the current file, starting from the location of the current line pointer. If the end of the file is reached and less than N lines are deleted, a warning is issued, but editing continues. The current value of the comment delimiters is used to determine the method of commenting, (see SetCommentStart). After the operation the pointer points to the line after the commented lines.

CommentToLineMatching quoted-regex
Use the current value of the comment delimiters set using SetCommentStart and SetCommentEnd to comment out lines from the current position in a file to a line matching the given regular expression in quotes.

DefineClasses "class1:class2:..."
Activate the following colon, comma or dot-separated list of classes if and only if the file is edited.

DeleteLinesAfterThisMatching quoted-regex
Delete lines after the current position which match the quoted expression.

DeleteLinesContaining quoted-string
Delete all lines containing the exact string quoted.

DeleteLinesMatching quoted-regex
Delete all lines matching the quoted regular expression.

DeleteLinesStarting quoted-string
Delete all lines beginning with the exact string quoted.

DeleteNLines quoted-string
Deletes up to N lines from the current file, starting from the location of the current line pointer. If the end of the file is reached and less than N lines are deleted, a warning is issued, but editing continues.

DeleteToLineMatching quoted-regex
Delete lines from the current position, up to but not including a line matching the regular expression in the quoted string. If no line matches the given expression, a warning is only printed in verbose mode, but all edits are immediately abandoned.

EditMode "Binary"
If set to binary, the file will be edited as if it were a non-ASCII file. See discussion below.
 
   EditMode "Binary"

EmptyEntireFilePlease
Deletes all lines from the current file.

ElseDefineClasses
See DefineClasses

EndGroup
Terminates a begin-end conditional structure.

EndLoop
Terminates a loop. See ForEachLineIn

Filter filteralias
Name a fiter for pruning file searches.

FixEndOfLine
The quoted string which follows may be either `dos' or `Unix' to fix the end of line character conventions to match these systems. This command should be executed last of all, since cfengine appends new lines with the conventions of the system on which is was complied during edit operations.

ForEachLineIn quoted-filename
This marks the beginning of a for-loop which reads successive lines from a named file. The result is like using SetLine for each line in the file. Nested loops are not permitted.

GotoLastLine
Moves the file pointer to the last line in the current file.

HashCommentLinesContaining quoted-string
Add a `#' to the start of any line containing the quoted string.

HashCommentLinesMatching quoted-regex
Add a `#' to the start of any line exactly matching the quoted regular expression.

HashCommentLinesStarting quoted-string
Add a `#' to the start of any line starting with the quoted string.

IncrementPointer quoted-number
Increments the value (in lines) of the file pointer by the number of lines specified in the quoted string (as a denary number). e.g. `"4"'. Negative values are equivalent to decrementing the pointer. If a request is made to increment/decrement outside of the file boundaries the pointer `bumps' into the boundary and remains there, i.e. either at start of file or end of file.

Inform quoted-string
Set to true or false, on or off to set inform level for this file. Default is off.

InsertFile quoted-string
Inserts the named file after the current line position in the file. This should be used in conjunction with a begin-end construction in order to avoid including the file every time cfengine is run. If the file does not exist, or cannot be opened, there is only a warning issued in verbose mode. Note if the file is empty, or if the current line pointer is not set, the file is inserted at the start of the file.

InsertLine quoted-string
Inserts the quoted string as a line at the current position in the file. After the insert, the file pointer is incremented by one so that subsequent inserted lines are placed after the first. This should probably be used in conjunction with the conditional begin-end tests to avoid lines being inserted on every run.

LocateLineMatching quoted-regex
Moves the current-position pointer to the start of the line matching the quoted regular expression. If there is no match, a warning is only issued in verbose mode, but all editing is immediately aborted. See also WarnIfNoLineMatching so that you can get an explicit warning, even out of verbose mode.

PercentCommentLinesContaining quoted-string
Add a `%' to the start of any line containing the quoted string.

PercentCommentLinesMatching quoted-regex
Add a `%' to the start of any line exactly matching the quoted regular.

PercentCommentLinesStarting quoted-string
Add a `%' to the start of any line starting with the quoted string.

Prepend quoted-string
Add a line containing the quoted string to the start of the file. This should be used in conjunction with the decision structures BeginGroupIfNoLineMatching and BreakIfLineMatches.

PrependIfNoLineMatching quoted-regex
A new version of the older PrependIfNoSuchLine with uses a regular expression instead of a literal string. The string prepended is the one set using SetLine.

PrependIfNoSuchLine quoted-string
Add a line containing the quoted string to the start of the file if the file doesn't contain the exact line already.

Recurse digit/inf
For recursive descents when editing whole file trees.

ReplaceLineWith quoted-string
Replace the line at the current position with the text in the quoted string. The file pointer remains pointing to this line after the change.

ReplaceAll quoted-regex With quoted-string
Replace all instances of strings matching the regular expression in the first quotes with the exact string in the second set of quotes, throughout the current file. Note that cfengine matches on a left to right basis, with the first match taking precedence, so if your regular expression matches text ambiguously it is the first occurrence which is replaced. For example, if you replace `cf.*' with `CFENGINE' and cfengine encounters a line `hello cfengine cfengine', then this will be replaced with `hello CFENGINE' even though two possible strings match the regular expression. On the other hand if the expression is not ambiguous, say replacing `cfengine' with `CFENGINE', then the result would be `hello CFENGINE CFENGINE'.

ReplaceLinesMatchingField quoted-number
This command replaces any lines in the current file with the current line set by SetLine or ForEachLineIn, if the lines are split into fields (e.g. the password file) separated by the SplitOn character (':' by default), and the corresponding fields match.

The idea behind this command was to be able to override global passwords (from a file which gets distributed) by new passwords in a local file. Rather than maintaining the files separately, this simply overrides the entries with the new ones.

Repository quoted string
This allows a local override of the Repository variable, on an item by item basis. If set to "off" or "none" it cancels the value of a global repository.

ResetSearch quoted-string
Sets the current-position pointer to the line number in the quoted string. `EOF' indicates the end of the file.

RunScript quoted-string
Executes the named script command. Before executing the script any edits are saved to disk. After the script has executed, cfengine reloads the file for any further editing operations. The script (which may be any executable program) is appended with two arguments: the name of the file which is being edited and the system hard class (e.g. sun4, ultrix etc.) of the system executing the script.

CAUTION: cfengine knows nothing about the success or failure of anything that is done during the execution of user scripts. This feature is to be used at the users own peril!

RunScriptIfLineMatching quoted-string
Executes the script named with the SetScript command only if the current file contains a line matching the quoted regular expression.

CAUTION: cfengine knows nothing about the success or failure of anything that is done during the execution of user scripts. This feature is to be used at the users own peril!

RunScriptIfNoLineMatching quoted-regex
Executes the script named with the SetScript command if the current file contains no line matching the quoted regular expression.

CAUTION: cfengine knows nothing about the success or failure of anything that is done during the execution of user scripts. This feature is to be used at the users own peril!

SetCommentStart quoted-string
Specify which string should be used for starting a comment using the commands CommentLineMatching and CommentLineStarting. The default is the hash symbol `#' followed by a single space.

SetCommentEnd quoted-string
Specify which string should be used for ending a comment using the commands CommentLineMatching and CommentLineStarting. The default is the empty string. For example, you could make C style comments by setting CommentStart to `/*' and comment end to `*/'.

SetLine quoted-string

Sets a current line value which can be appended using AppendIfNoLineMatching using a regular expression.

SetScript quoted-string
Sets the name of a user-supplied script for editing the current file.

SlashCommentLinesContaining quoted-string
Add a `//' to the start of any line containing the quoted string.

SlashCommentLinesMatching quoted-regex
Add a `//' to the start of any line exactly matching the quoted regular expression.

SlashCommentLinesStarting quoted-string
Add a `//' to the start of any line starting with the quoted string.

SplitOn quoted-string
This defines a single character which is to be interpreted as a field separator for editing files with columns. The default value for this is `:', as is used in the password and group files. It is used in conjunction with ReplaceLinesMatchingField.

Syslog quoted-string
Set to true or false, on or off to set inform level for this file. Default is off.

Umask quote mode
Set local umask for file creation and script execution.

UnCommentLinesContaining quoted-string
Uncomment all lines in file containing the quoted string as a substring. The comment delimiters are assumed to be those set using SetCommentStart and SetCommentEnd.

UnCommentLinesMatching quoted-regex
Uncomment all lines in file matching the quoted regular expression. The comment delimiters are assumed to be those set using SetCommentStart and SetCommentEnd.

UnCommentNLines quoted-string
Uncomments N lines starting from the current position, using the currently defined method for commenting. Note that the comment start and end symbols are removed independently, i.e. they are not matched, so that a comment may be spread over several lines. e.g. If using C style `/*' and `*/' comments, the command UnCommentNLines "3" would uncomment
 
 /* 1 */
 /* 2 */
 /* 3 */
and also
 
 /* 1 
    2
    3 */

UnsetAbort quoted-string
Switches off the feature AbortAtLineMatching.

UseShell "false"
Normally cfengine uses a shell based exec function to run scripts during editing. This involves the inheritance of environment variables and path, which carries with it an inherent security risk. Setting this value to false causes execution to execute without an encapsulating shell.

WarnIfLineContaining quoted-string
Issue a warning if the quoted string is found as a substring of one or more lines in the file.

WarnIfLineMatching quoted-regex
Issue a warning if the quoted regular expression matches one or more lines in the file.

WarnIfLineStarting quoted-string
Issue a warning if the quoted string matches the start of one or more lines in the file.

WarnIfNoLineContaining quoted-string
Issue a warning if the quoted string is not contained in one or more lines in the file.

WarnIfNoLineMatching reg-ex
Issue a warning if the quoted regular expression does not match one or more lines in the file.

WarnIfNoLineStarting quoted-string
Issue a warning if the quoted string is not found at the start of one or more lines in the file.

WarnIfNoSuchLine quoted-regex
Issue a warning if the quoted regular expression does not match one or more lines in the file.

A limited number of operations can also be performed on purely binary files, e.g. compiled programs, in order to search for strings or viral code, or to modify strings within a program. Binary mode is a mutually exclusive, separate mode to normal editing. The limit on the size of binary files is set by editbinaryfilesize in control.

ReplaceAll regex With literal

Replaces occurrences of the matched regular expression with\ the provided literal text, only if the length of the literal substitute is less than or equal to the length of the located string. If the replacement string is shorter, it is padded with ascii spaces (character 32) by default. The padding character can be changed by setting BinaryPaddingChar in control. Padding with a null byte would lead to corruption of text within a program.

WarnIfContainsString regex/literal
Yields a warning if the literal string or regular expression matches. Cfengine first attempts a literal match and then a regular expression match.

WarnIfContainsFile filename
Yields a warning if the contents of the named file exactly match part of the file which is being edited. This can be used to search for binary data which cannot be typed directly into the cfengine program, e.g. virus signatures.

It is suggested that you use these editing functions with caution. Although all possible safeguards have been incorporated into them, it is still possible through carelessness to do damage to important files on your system. Always test editing programs carefully before committing them to your global site configuration.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003