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"

      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, See section FAQs and Tips.

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. New files are created with mode 644, 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 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.

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.

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

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.

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-string

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 See section FAQs and Tips.

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.

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.

Go to the first, previous, next, last section, table of contents.