struct Libcrown

• Libcrown
• Struct
• Value
• Object

Overview

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

Defined in:

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 crystal libcrown = Libcrown.new nil

• .new(shadow : String = "", passwd : String = "", group : String = "")

  Parse shadow, passwd and group files from strings.

Class Method Summary

• .validate_name(name : String) : Nil

  Validates a name for use as user or group name.

Instance Method Summary

• #add_group(group_entry : Group, gid : UInt32 = available_gid) : UInt32

  Add a new group.

• #add_group_member(uid : UInt32, gid : UInt32) : Set(String)

  Adds/ensure an user is member of the group.

• #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_group : String

  Builds #groups to group.

• #build_passwd : String

  Builds #users to passwd.

• #build_shadow : String

  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

  Raise if an id is taken.

• #check_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

  Deletes a group.

• #del_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 : Path | Nil

  Group file, commonly stored in /etc/group.

• #groups : Hash(UInt32, Group)

  System groups.

• #passwd_file : Path | Nil

  User file, commonly stored in /etc/passwd.

• #passwords : Hash(String, Password)

  User's passwords.

• #shadow_file : Path | Nil

  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 : Hash(UInt32, User)

  System users.

• #write : Nil

  Save the state by writing the files to the file system.

Constructor Detail

libcrown = Libcrown.new nil

Class Method Detail

Instance Method Detail