LCFG::Utils::PasswdFile - Read and Write Unix passwd files
This documentation refers to LCFG::Utils::PasswdFile version 1.2.1
use LCFG::Utils::PasswdFile;
my $passwd = LCFG::Utils::PasswdFile->new_from_file();
my @users = $passwd->list_users;
my @uids = $passwd->list_uids;
my @entries = $passwd->list_entries;
# Add/Delete/Update entries
my $root = $passwd->get_entry_for_uid(0);
$root->shell('/bin/sh');
$passwd->remove_entry_for_name('fred');
$passwd->to_file;This module provides an object-oriented interface to the Unix passwd file. It can parse a passwd file and then provide lists of UIDs and usernames. There is support for adding, removing and updating entries. Support is also provided for finding the differences between two different passwd files.
This is a reference to a hash which maps the UID to the associated passwd file entry. Normally it is better to find user entries by using the get_entry_for_uid and has_entry_for_uid methods. Do not add and remove entries directly from this hash use the add_entry and remove_entry_for_uid methods.
This is a reference to a hash which maps the username to the associated passwd file entry. Normally it is better to find user entries by using the get_entry_for_name and has_entry_for_name methods. Do not add and remove entries directly from this hash use the add_entry and remove_entry_for_name methods.
The following class methods are available.
This will create a new, empty, LCFG::Utils::PasswdFile object to which entries can be added.
This method will create a new LCFG::Utils::PasswdFile object based on the contents of the specified Unix passwd file. If no file name is given then the default, /etc/passwd, will be parsed.
The add_entry method is used to add an entry for each line. If multiple identical lines are found the later ones will be ignored. If entries with the same UID and username but with other fields differing are found then the later entry wins. Otherwise, if multiple entries are found for a UID with different usernames or multiple entries are found for a username with different UIDs this method will die.
The following methods can be called on an LCFG::Utils::PasswdFile object.
This will write all the passwd file entries stored in the LCFG::Utils::PasswdFile object into the specified file. If no file name is given then the default, /etc/passwd, will be used, note that, typically, root access will be required to write to that file. The entries will be written out in numerical UID order.
This takes a second LCFG::Utils::PasswdFile object and returns references to 3 lists. The first is the list of entries which are only in this object, the second is the list of entries which are only in the other object, the third is the list of entries which appear in both but have some differences. For example:
my $passwd1 = LCFG::Utils::PasswdFile->new_from_file("/etc/passwd");
my $passwd2 = LCFG::Utils::PasswdFile->new_from_file("/etc/passwd.new");
my ( $missing, $extras, $diffs ) = $passwd1->diff($passwd2);Each item in the missing and extras lists is an LCFG::Utils::PasswdFile::Entry object. Each item in the diffs list is an array-reference to a pair of LCFG::Utils::PasswdFile::Entry objects, the first entry is from this passwd object, the second entry is from the other passwd object.
All three lists are sorted numerically on the UID.
This returns the list of entries (i.e. LCFG::Utils::PasswdFile::Entry objects) in the passwd file. The returned list will be sorted according to the UID field.
This returns the list of UIDs in this passwd file. The returned list will be sorted numerically.
This returns the list of usernames in this passwd file. The returned list will be sorted alphabetically.
This method returns a boolean which signifies whether or not the UID is currently used in the passwd file.
This method will return the LCFG::Utils::PasswdFile::Entry object associated with the specified UID. If no entry is found for the specified UID then this method will die.
This method returns a boolean which signifies whether or not the username is currently used in the passwd file.
This method will return the LCFG::Utils::PasswdFile::Entry object associated with the specified username. If no entry is found for the specified username then this method will die.
This method will add an LCFG::Utils::PasswdFile::Entry object to the list of entries for the passwd file. It can take a string with the fields delimited using the standard colon (:), or a reference to a hash of the fields required to create an LCFG::Utils::PasswdFile::Entry object, or a previously assembled LCFG::Utils::PasswdFile::Entry object.
If multiple identical lines are found the later ones will be ignored. If entries with the same UID and username but with other fields differing are found then the later entry wins. Otherwise, if multiple entries are found for a UID with different usernames or multiple entries are found for a username with different UIDs this method will die.
This takes an LCFG::Utils::PasswdFile::Entry object and removes a matching entry from the stored list of entries for the passwd file. If the entry is not currently stored then this error does not fail. If incompatible entries are found for the UID or username then this method will fail.
This method will remove the entry associated with the specified UID. Internally it uses the get_entry_for_uid method so if there is no entry for this UID the method will fail. If this is a problem then check for existence first using the has_entry_for_uid method.
This method will remove the entry associated with the specified username. Internally it uses the get_entry_for_name method so if there is no entry for this username the method will fail. If this is a problem then check for existence first using the has_entry_for_name method.
This module requires List::MoreUtils, Readonly and Try::Tiny.
LCFG::Utils::PasswdFile::Entry, LCFG::Utils::GroupFile, LCFG::Utils::GroupFile::Entry, LCFG::Component::Auth
This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.
Scientific5, Scientific6, Fedora13
Please report any bugs or problems (or praise!) to bugs@lcfg.org, feedback and patches are also always very welcome.
Alastair Scobie <ascobie@inf.ed.ac.uk>, Stephen Quinney <squinney@inf.ed.ac.uk>Copyright (C) 2011 University of Edinburgh. All rights reserved.This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.