Tracking down errors

Every now and then, you'll run into a config file that augeas can't parse. It may be a bug in augeas, a limitation in the lens, or it might be an actual problem in the config file. Either way, the first step in solving the problem is tracking down the exact location in the config file that augeas couldn't handle.

The primary symptom of an inability to parse a config file is that the file won't show up under the /files tree. For example, let's say that we have a problem parsing the sudoers file. If you look for it with the augtool command ls /files/etc the sudoers entry will be missing.

The first step is to verify that augeas really did try to parse the file, but failed. You can use the following command to ask augeas for a list of all nodes with errors in them.

 augtool> match /augeas//error
 /augeas/files/etc/sudoers/error = parse_failed

We now have confirmation that augeas took a pass at the sudoers file, and failed. Now we retrieve the available details of the error, using the path we found with the match command. The exact data that are returned depends on the version of augeas you're using. In version 0.5.0 and later, it will tell you the exact line and character in the file where it found the error.

 augtool> ls /augeas/files/etc/sudoers/error/
 pos = 1848
 line = 58
 char = 0
 message = Short iteration

This tells you to start looking at the first character of line 58 in the /etc/sudoers file for the problem.

In version 0.4.2 and earlier, however, all you have to go by is the pos parameter.

 augtool> ls /augeas/files/etc/sudoers/error/
 pos = 1848
 message = Short iteration

The pos parameter is the number of bytes into the file that the problematic block of text occured. Since we already know the file to look in to find the error, you can either jump to that point with your favourite text editor, or just use this quick and dirty trick.

 ## Next comes the main part: which users can run what software on 
 ## which machines (the sudoers file can be shared between multiple
 ## systems).
 ## Syntax:
 <... rest of file ...>

We use the dd command, telling to read through the file with a block size of 1 byte, and to skip the first 1848 bytes, taken from the pos parameter above. You're now looking at the point in the file where augeas found that it couldn't handle something - in this case, it didn't like the Defaults line.

At this point, you still have to figure out, either by trial and error on the file or reading the lens, exactly why augeas couldn't parse the file, but you at least can be reasonably sure that you're looking in the right place.