'\" t
.\"     Title: realm
.\"    Author: Stef Walter <stef@thewalter.net>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 10/01/2014
.\"    Manual: User Commands
.\"    Source: realmd
.\"  Language: English
.\"
.TH "REALM" "8" "10/01/2014" "realmd" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
realm \- Manage enrollment in realms
.SH "SYNOPSIS"
.HP \w'\fBrealm\ discover\fR\ 'u
\fBrealm discover\fR [realm\-name]
.HP \w'\fBrealm\ join\fR\ 'u
\fBrealm join\fR [\-U\ user] [realm\-name]
.HP \w'\fBrealm\ leave\fR\ 'u
\fBrealm leave\fR [\-U\ user] [realm\-name]
.HP \w'\fBrealm\ list\fR\ 'u
\fBrealm list\fR
.HP \w'\fBrealm\ permit\fR\ 'u
\fBrealm permit\fR [\-ax] [\-R\ realm] {user@domain...}
.HP \w'\fBrealm\ deny\fR\ 'u
\fBrealm deny\fR \-a [\-R\ realm]
.SH "DESCRIPTION"
.PP
\fBrealm\fR
is a command line tool that can be used to manage enrollment in kerberos realms, like Active Directory domains or IPA domains\&.
.PP
See the various sub commands below\&. The following global options can be used:
.PP
\fB\-\-install=/path\fR
.RS 4
Run in install mode\&. This makes realmd chroot into the specified directory and place files in appropriate locations for use during an installer\&. No packages will be installed or services will be started when running in this mode\&.
.RE
.PP
\fB\-\-unattended\fR
.RS 4
Run in unattended mode without prompting for input\&.
.RE
.PP
\fB\-\-verbose, \-v\fR
.RS 4
Display verbose diagnostics while doing running commands\&.
.RE
.SH "DISCOVER"
.PP
Discover a realm and its capabilities\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm discover
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm discover domain\&.example\&.com
.fi
.if n \{\
.RE
.\}
.PP
After discovering a realm, its name, type and capabilities are displayed\&.
.PP
If no domain is specified, then the domain assigned through DHCP is used as a default\&.
.PP
The following options can be used:
.PP
\fB\-\-all\fR
.RS 4
Show all discovered realms (in various configurations)\&.
.RE
.PP
\fB\-\-client\-software=xxx\fR
.RS 4
Only discover realms for which we can use the given client software\&. Possible values include
\fIsssd\fR
or
\fIwinbind\fR\&.
.RE
.PP
\fB\-\-server\-software=xxx\fR
.RS 4
Only discover realms which run the given server software\&. Possible values include
\fIactive\-directory\fR
or
\fIipa\fR\&.
.RE
.PP
\fB\-\-membership\-software=xxx\fR
.RS 4
Only discover realms for which the given membership software can be used to subsequently perform enrollment\&. Possible values include
\fIsamba\fR
or
\fIadcli\fR\&.
.RE
.SH "JOIN"
.PP
Configure the local machine for use with a realm\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm join domain\&.example\&.com
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm join \-\-user=admin \-\-computer\-ou=OU=Special domain\&.example\&.com
.fi
.if n \{\
.RE
.\}
.PP
The realm is first discovered, as we would with the
\fBdiscover\fR
command\&. If no domain is specified, then the domain assigned through DHCP is used as a default\&.
.PP
After a successful join, the computer will be in a state where it is able to resolve remote user and group names from the realm\&. For kerberos realms, a computer account and host keytab is created\&.
.PP
Joining arbitrary kerberos realms is not supported\&. The realm must have a supported mechanism for joining from a client machine, such as Active Directory or IPA\&.
.PP
Unless a
\-\-user
is explicitly specified, an automatic join is attempted first\&. Automatic joins require pre\-configuration on the domain side, and may not be supported by all domains\&.
.PP
Note that the
\-\-user,
\-\-no\-password, and
\-\-one\-time\-password
options are mutually exclusive\&. At most one of them can be specified\&.
.PP
It is generally possible to use kerberos credentials to perform a join operation\&. Use the
\fBkinit\fR
command to acquire credentials prior to starting the join\&. Do not specify the
\fB\-\-user\fR
argument, the user will be selected automatically from the credential cache\&. The
\fBrealm\fR
respects the
KRB5_CCACHE
environment variable, but uses the default kerberos credential cache if it\*(Aqs not present\&. Not all types of servers can be joined using kerberos credentials, some (like IPA) insist on prompting for a password\&.
.PP
The following options can be used:
.PP
\fB\-\-user=xxx\fR
.RS 4
The user name to be used to authenticate with when joining the machine to the realm\&. You will be prompted for a password\&.
.RE
.PP
\fB\-\-computer\-ou=OU=xxx\fR
.RS 4
The distinguished name of an organizational unit to create the computer account\&. The exact format of the distinguished name depends on the client software and membership software\&. You can usually omit the root DSE portion of distinguished name\&. This is an Active Directory specific option\&.
.RE
.PP
\fB\-\-no\-password\fR
.RS 4
Perform the join automatically without a password\&.
.RE
.PP
\fB\-\-one\-time\-password=xxxx\fR
.RS 4
Perform the join using a one time password specified on the command line\&. This is not possible with all types of realms\&.
.RE
.PP
\fB\-\-client\-software=xxx\fR
.RS 4
Only join realms for which we can use the given client software\&. Possible values include
\fIsssd\fR
or
\fIwinbind\fR\&. Not all values are supported for all realms\&. By default the client software is automatically selected\&.
.RE
.PP
\fB\-\-server\-software=xxx\fR
.RS 4
Only join realms for run the given server software\&. Possible values include
\fIactive\-directory\fR
or
\fIipa\fR\&.
.RE
.PP
\fB\-\-membership\-software=xxx\fR
.RS 4
The software to use when joining to the realm\&. Possible values include
\fIsamba\fR
or
\fIadcli\fR\&. Not all values are supported for all realms\&. By default the membership software is automatically selected\&.
.RE
.PP
\fB\-\-user\-principal=\fR\fB\fIhost/name@REALM\fR\fR
.RS 4
Set the userPrincipalName field of the computer account to this kerberos principal\&. If you omit the value for this option, then a principal will be set in the form of
host/shortname@REALM
.RE
.SH "LEAVE"
.PP
Deconfigure the local machine for use with a realm\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm leave
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm leave domain\&.example\&.com
.fi
.if n \{\
.RE
.\}
.PP
If no realm name is specified, then the first configured realm will be used\&.
.PP
The following options can be used:
.PP
\fB\-\-client\-software=xxx\fR
.RS 4
Only leave the realm which is using the given client software\&. Possible values include
\fIsssd\fR
or
\fIwinbind\fR\&.
.RE
.PP
\fB\-\-server\-software=xxx\fR
.RS 4
Only leave the realm which is using the given server software\&. Possible values include
\fIactive\-directory\fR
or
\fIipa\fR\&.
.RE
.PP
\fB\-\-remove\fR
.RS 4
Remove or disable computer account from the directory while leaving the realm\&. This will usually prompt for a pasword\&.
.RE
.PP
\fB\-\-user\fR
.RS 4
The user name to be used to authenticate with when leaving the realm\&. You will be prompted for a password\&. Implies
\fB\-\-remove\fR\&.
.RE
.SH "LIST"
.PP
List all the discovered and configured realms\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm list
.fi
.if n \{\
.RE
.\}
.PP
By default, realms that have been discovered, but not configured (using the
\fBjoin\fR
command), are not displayed\&. Also, by default, the list of realm details displayed is verbose\&. The options below can be used to change this default behavior
.PP
The following options can be used:
.PP
\fB\-\-all\fR
.RS 4
Show all discovered realms (whether or not they have been configured)\&.
.RE
.PP
\fB\-\-name\-only\fR
.RS 4
Display only realm names (as opposed to verbose output)\&.
.RE
.SH "PERMIT"
.PP
Permit local login by users of the realm\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm permit \-\-all
$ realm permit user@example\&.com
$ realm permit DOMAIN\e\eUser2
$ realm permit \-\-withdraw user@example\&.com
.fi
.if n \{\
.RE
.\}
.PP
The current login policy and format of the user names can be seen by using the
\fBrealm list\fR
command\&.
.PP
The following options can be used:
.PP
\fB\-\-all, \-a\fR
.RS 4
Permit logins using realm accounts on the local machine according to the realm policy\&.This usually defaults to allowing any realm user to log in\&.
.RE
.PP
\fB\-\-groups, \-g\fR
.RS 4
Treat the specified names as groups rather than user login names\&. Permit login by users in the specified groups\&.
.RE
.PP
\fB\-\-realm, \-R\fR
.RS 4
Specify the of the realm to change login policy for\&.
.RE
.PP
\fB\-\-withdraw, \-x\fR
.RS 4
Remove a login from the list of realm accounts permitted to log into the machine\&.
.RE
.SH "DENY"
.PP
Deny local login by realm accounts\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ realm deny \-\-all
.fi
.if n \{\
.RE
.\}
.PP
This command prevents realm accounts from logging into the local machine\&. Use
\fBrealm permit\fR
to restrict logins to specific accounts\&.
.PP
The following options can be used:
.PP
\fB\-\-all, \-a\fR
.RS 4
This option should be specified
.RE
.PP
\fB\-\-realm, \-R\fR
.RS 4
Specify the name of the realm to deny users login to\&.
.RE
.SH "AUTHOR"
.PP
\fBStef Walter\fR <\&stef@thewalter\&.net\&>
.RS 4
Maintainer
.RE