passwd(4), shadow(4) and group(4)

Interface to read a standard Unix passwd, shadow and group file-format

Install

npm install etc-passwd

Usage

var passwd = require('etc-passwd');

Functions

passwd.getUsers([file])

Get all users found in file. This functions returns an instance of EventEmitter.

The optional parameter file defaults to /etc/passwd

.on('user', function(user) {})

Returns an object whenever a user is found

.on('end', function() {})

Called when the file is done being read

passwd.getUsers([file], callback(err, users))

If a callback is supplied as the last argument, the entire file will be read at once, and the results will be returned as a list of user objects. This is good for convenience, but can produce unnecessary overhead on systems with a lot of users.

---

passwd.getUser({'username':'root'}, [file], callback(err, user))

Look for a specific username in file (defaults to /etc/passwd). This will use the EventEmitter to avoid loading the entire file into memory and return the callback when the user is found. If the user is not found err will be set and user will be null. You can specify any attribute to look for as the first argument.

---

passwd.getGroups([file])

Get all groups found in file. This functions returns an instance of EventEmitter.

The optional parameter file defaults to /etc/group

.on('group', function(group) {})

Returns an object whenever a group is found

.on('end', function() {})

Called when the file is done being read

passwd.getGroups([file], callback(err, groups))

If a callback is supplied as the last argument, the entire file will be read at once, and the results will be returned as a list of group objects. This is good for convenience, but can produce unnecessary overhead on systems with a lot of groups.

---

passwd.getGroup({'groupname':'wheel'}, [file], callback(err, group))

Look for a specific groupname in file (defaults to /etc/group). This will use the EventEmitter to avoid loading the entire file into memory and return the callback when the group is found. If the group is not found err will be set and group will be null. You can specify any attribute to look for as the first argument.

---

passwd.getShadows([file])

Get all shadow entries found in file. This functions returns an instance of EventEmitter.

The optional parameter file defaults to /etc/shadow

.on('shadow', function(shadow) {})

Returns an object whenever a shadow entry is found

.on('end', function() {})

Called when the file is done being read

passwd.getShadows([file], callback(err, shadows))

If a callback is supplied as the last argument, the entire file will be read at once, and the results will be returned as a list of shadow objects. This is good for convenience, but can produce unnecessary overhead on systems with a lot of shadow entries.

---

passwd.getShadow({'username':'root'}, [file], callback(err, shadow))

Look for a specific username in file (defaults to /etc/shadow). This will use the EventEmitter to avoid loading the entire file into memory and return the callback when the shadow-entry is found. If the shadow entry is not found err will be set and shadow will be null. You can specify any attribute to look for as the first argument.

Example

passwd.getUsers()

An example of using the EventEmitter interface to find users

var passwd = require('passwd'),
    users = passwd.getUsers();
 
users.on('user', function(user) {
  console.log(JSON.stringify(user));
});
users.on('end', function() {
  console.log('Done.');
});

{"username":"nobody","password":"*","uid":-2,"gid":-2,"comments":"Unprivileged User","home":"/var/empty","shell":"/usr/bin/false"}
{"username":"root","password":"*","uid":0,"gid":0,"comments":"System Administrator","home":"/var/root","shell":"/bin/sh"}
...
Done.

passwd.getUsers(callback(users))

Using the callback instead of the EventEmitter to get the results

var passwd = require('passwd');
passwd.getUsers(function(users) {
  console.log(JSON.stringify(users));
});

[
{"username":"nobody","password":"*","uid":-2,"gid":-2,"comments":"Unprivileged User","home":"/var/empty","shell":"/usr/bin/false"},
{"username":"root","password":"*","uid":0,"gid":0,"comments":"System Administrator","home":"/var/root","shell":"/bin/sh"},
...
]

passwd.getUser()

As for a specific user on the system

var passwd = require('etc-passwd');
passwd.getUser({'username':'root'}, function(err, user) {
  console.log(JSON.stringify(user));
});

{
  "username": "root",
  "password": "*",
  "uid": 0,
  "gid": 0,
  "comments": "System Administrator",
  "home": "/var/root",
  "shell": "/bin/sh"
}

---

passwd.getGroups()

An example of using the EventEmitter interface to find groups

var passwd = require('passwd'),
    groups = passwd.getGroups();
 
groups.on('group', function(group) {
  console.log(JSON.stringify(group));
});
groups.on('end', function() {
  console.log('Done.');
});

{"groupname":"nobody","password":"*","gid":-2,"users":[]}
{"groupname":"nogroup","password":"*","gid":-1,"users":[]}
...
Done.

passwd.getGroups(callback(groups))

Using the callback instead of the EventEmitter to get the results

var passwd = require('passwd');
passwd.getGroups(function(groups) {
  console.log(JSON.stringify(groups));
});

[
{"groupname":"nobody","password":"*","gid":-2,"users":[]}
{"groupname":"nogroup","password":"*","gid":-1,"users":[]}
...
]

passwd.getGroup()

var passwd = require('etc-passwd');
passwd.getGroup({'groupname':'wheel'}, function(err, group) {
  console.log(JSON.stringify(group));
});

{
  "groupname": "wheel",
  "password": "*",
  "gid": 0,
  "users": [
    "root"
  ]
}

License

MIT Licensed