.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Rex::Commands::User 3pm"
.TH Rex::Commands::User 3pm "2023-08-09" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rex::Commands::User \- Manipulate users and groups
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
With this module you can manage user and groups.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Rex::Commands::User;
\&
\& task "create\-user", "remoteserver", sub {
\&   create_user "root",
\&     uid         => 0,
\&     home        => \*(Aq/root\*(Aq,
\&     comment     => \*(AqRoot Account\*(Aq,
\&     expire      => \*(Aq2011\-05\-30\*(Aq,
\&     groups      => [ \*(Aqroot\*(Aq, \*(Aq...\*(Aq ],
\&     password    => \*(Aqblahblah\*(Aq,
\&     system      => 1,
\&     create_home => TRUE,
\&     shell       => \*(Aq/bin/bash\*(Aq,
\&     ssh_key     => "ssh\-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQChUw...";
\& };
.Ve
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.ie n .SS "account($name, %option)"
.el .SS "account($name, \f(CW%option\fP)"
.IX Subsection "account($name, %option)"
Manage user account.
.PP
.Vb 10
\& account "krimdomu",
\&   ensure         => "present",  # default
\&   uid            => 509,
\&   home           => \*(Aq/root\*(Aq,
\&   comment        => \*(AqUser Account\*(Aq,
\&   expire         => \*(Aq2011\-05\-30\*(Aq,
\&   groups         => [ \*(Aqroot\*(Aq, \*(Aq...\*(Aq ],
\&   login_class    => \*(Aqstaff\*(Aq,   # on OpenBSD
\&   password       => \*(Aqblahblah\*(Aq,
\&   crypt_password => \*(Aq*\*(Aq, # on Linux, OpenBSD and NetBSD
\&   system         => 1,
\&   create_home    => TRUE,
\&   shell          => \*(Aq/bin/bash\*(Aq,
\&   ssh_key        => "ssh\-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQChUw...";
.Ve
.PP
There is also a no_create_home option similar to create_home but doing the
opposite. If both used, create_home takes precedence as it the preferred option
to specify home directory creation policy.
.PP
If none of them are specified, Rex follows the remote system's home creation
policy.
.PP
The crypt_password option specifies the encrypted value as found in
/etc/shadow; on Linux special values are '*' and '!' which mean
\&'disabled password' and 'disabled login' respectively.
.SS "create_user($user => {})"
.IX Subsection "create_user($user => {})"
Create or update a user.
.PP
This function supports the following hooks:
.IP "before" 4
.IX Item "before"
This gets executed before the user is created. All original parameters are passed to it.
.IP "after" 4
.IX Item "after"
This gets executed after the user is created. All original parameters, and the user's \f(CW\*(C`UID\*(C'\fR are passed to it.
.SS "get_uid($user)"
.IX Subsection "get_uid($user)"
Returns the uid of \f(CW$user\fR.
.SS "get_user($user)"
.IX Subsection "get_user($user)"
Returns all information about \f(CW$user\fR.
.SS "user_groups($user)"
.IX Subsection "user_groups($user)"
Returns group membership about \f(CW$user\fR.
.SS "\fBuser_list()\fP"
.IX Subsection "user_list()"
Returns user list via getent passwd.
.PP
.Vb 5
\& task "list_user", "server01", sub {
\&   for my $user (user_list) {
\&     print "name: $user / uid: " . get_uid($user) . "\en";
\&   }
\& };
.Ve
.SS "delete_user($user)"
.IX Subsection "delete_user($user)"
Delete a user from the system.
.PP
.Vb 4
\& delete_user "trak", {
\&   delete_home => 1,
\&   force     => 1,
\& };
.Ve
.SS "lock_password($user)"
.IX Subsection "lock_password($user)"
Lock the password of a user account. Currently this is only
available on Linux (see passwd \-\-lock) and OpenBSD.
.SS "unlock_password($user)"
.IX Subsection "unlock_password($user)"
Unlock the password of a user account. Currently this is only
available on Linux (see passwd \-\-unlock) and OpenBSD.
.SS "create_group($group, {})"
.IX Subsection "create_group($group, {})"
Create or update a group.
.PP
.Vb 4
\& create_group $group, {
\&   gid => 1500,
\&   system => 1,
\& };
.Ve
.SS "get_gid($group)"
.IX Subsection "get_gid($group)"
Return the group id of \f(CW$group\fR.
.SS "get_group($group)"
.IX Subsection "get_group($group)"
Return information of \f(CW$group\fR.
.PP
.Vb 1
\& $info = get_group("wheel");
.Ve
.SS "delete_group($group)"
.IX Subsection "delete_group($group)"
Delete a group.