Safe High level API to manipulate users, groups and passwords from /etc/passwd, /etc/group and /etc/shadow.
It's highly recommended to use this wrapper for any manipulation. users, groups and passwords
getters have to be considered read-only.
require "libcrown"
# Root permissions are needed
libcrown = Libcrown.new
# Add a new group
libcrown.add_group Libcrown::Group.new("new_group"), 100_u32
# Add a new user with `new_group` as its main group
new_user = Libcrown::User.new(
name: "new_user",
gid: 100_u32,
gecos_comment: "This is a newly created user",
home_directory: "/home/new_user",
login_shell: "/bin/sh",
)
libcrown.add_user new_user
# Save the modifications to the disk
libcrown.write
Constructors
new(shadow_file : Path | Nil = Path["/etc/shadow"], passwd_file : Path | Nil = Path["/etc/passwd"], group_file : Path | Nil = Path["/etc/group"])
Requires root permissions to read the shadow file and write passwd and group files
As non-root, to only read passwd and group files
libcrown = Libcrown.new nil
new(shadow : String = "", passwd : String = "", group : String = "")
Parse shadow, passwd and group files from strings.
Class methods
validate_name(name : String) : Nil
Validates a name for use as user or group name.
Instance methods
add_group(group_entry : Group, gid : UInt32 = available_gid) : UInt32
Sourceadd_group_member(uid : UInt32, gid : UInt32) : Set(String)
Adds/ensure an user is member of the group. Not needed if the group is the main one of the user.
add_user(user_entry : User, uid : UInt32 = available_uid, password_entry : Password = Password.new) : UInt32
Adds a new user along, to an existing group.
available_gid(start : UInt32 = 0_u32) : UInt32
Returns the first available gid.
available_id(start : UInt32 = 0_u32) : UInt32
Finds the first available user and group id.
available_uid(start : UInt32 = 0_u32) : UInt32
Returns the first available uid.
build_shadow
Builds passwords to shadow.
change_password(uid : UInt32, password : Password) : Password
Change the user's password entry.
check_available_gid(id : UInt32) : UInt32
Raise if the gid is taken.
check_available_group(name : String) : String
Raise if the group name is taken.
check_available_id(id : UInt32) : UInt32
Sourcecheck_available_name(name : String) : String
Raise if the name is taken.
check_available_uid(id : UInt32) : UInt32
Raise if the uid is taken.
check_available_user(name : String) : String
Raise if the user name is taken.
del_group(gid : UInt32) : Group | Nil
Sourcedel_group_member(uid : UInt32, gid : UInt32) : Set(String)
Delete?/ensure an user isn't a member of the group.
del_user(uid : UInt32, del_group : Bool = false) : User | Nil
Delete an user and optionally with its main group, returns the deleted User.
get_password(uid : UInt32) : Password
Get the user's password entry.
group_file
Group file, commonly stored in /etc/group.
groups
System groups. Modifying it directly is unsafe.
passwd_file
User file, commonly stored in /etc/passwd.
passwords
User's passwords. Modifying it directly is unsafe.
shadow_file
Password file, commonly stored in /etc/shadow.
to_gid(name : String) : UInt32
Returns an gid matching the name, else raise.
to_gid(name : String, &)
Yields each gid matching the name.
to_gid?(name : String) : UInt32 | Nil
Returns an gid matching the name, if any.
to_uid(name : String) : UInt32
Returns an uid matching the name, else raise.
to_uid(name : String, &)
Yields each uid matching the name.
to_uid?(name : String) : UInt32 | Nil
Returns an uid matching the name, if any.
user_group_member?(uid : UInt32, gid : UInt32) : Bool
Returns true if the user is a member of the group or if the group is primary one of the user.
users
System users. Modifying it directly is unsafe.
write
Save the state by writing the files to the file system.