## org.freedesktop.realmd.Realm

org.freedesktop.realmd.Realm — a realm

## Methods

    Deconfigure       (IN  a{sv} options);
    ChangeLoginPolicy (IN  s     login_policy,
                       IN  as    permitted_add,
                       IN  as    permitted_remove,
                       IN  a{sv} options);

## Properties

    Name                 readable   s
    Configured           readable   s
    SupportedInterfaces  readable   as
    Details              readable   a(ss)
    RequiredPackages     readable   as
    LoginFormats         readable   as
    LoginPolicy          readable   s
    PermittedLogins      readable   as
    PermittedGroups      readable   as

## Description

Represents one realm.

Contains generic information about a realm, and useful properties for introspecting what kind of realm this is and how to work with the realm.

Use "Realms" or #Discover() to get access to some kerberos realm objects.

Realms will always implement additional interfaces, such as org.freedesktop.realmd.Kerberos. Do not assume that all realms implement that kerberos interface. Use the "SupportedInterfaces" property to see which interfaces are supported.

Different realms support various ways to configure them on the system. Use the "Configured" property to determine if a realm is configured. If it is configured, the property will be set to the interface of the mechanism that was used to configure it.

To configure a realm, look in the "SupportedInterfaces" property for a recognized purpose-specific interface that can be used for configuration, such as the org.freedesktop.realmd.KerberosMembership interface and its #Join() method.

To deconfigure a realm from the current system, you can use the #Deconfigure() method. In addition, some of the configuration specific interfaces provide methods to deconfigure a realm in a specific way, such as the #Leave() method.

The various properties are guaranteed to have been updated before the operation methods return, if they change state.

## Method Details

### The Deconfigure() method

    Deconfigure (IN  a{sv} options);

deconfigure this realm Deconfigure this realm from the local machine with standard default behavior.

The behavior of this method depends on the which configuration interface is present in the org.freedesktop.realmd.Realm.Configured property. It does not always delete membership accounts in the realm, but just reconfigures the local machine so it no longer is configured for the given realm. In some cases the implementation may try to update membership accounts, but this is not guaranteed.

Various configuration interfaces may support more specific ways to deconfigure a realm in a specific way, such as the #Leave() method.

`options` can contain, but is not limited to, the following values:

- `operation`: a string identifier chosen by the client, which can then later be passed to Cancel() in order to cancel the operation

This method requires authorization for the PolicyKit action called `org.freedesktop.realmd.deconfigure-realm`.

In addition to common DBus error results, this method may return:

- `org.freedesktop.realmd.Error.Failed`: may be returned if the deconfigure failed for a generic reason.

- `org.freedesktop.realmd.Error.Cancelled`: returned if the operation was cancelled.

- `org.freedesktop.realmd.Error.NotAuthorized`: returned if the calling client is not permitted to deconfigure a realm.

- `org.freedesktop.realmd.Error.NotConfigured`: returned if this realm is not configured on the machine.

- `org.freedesktop.realmd.Error.Busy`: returned if the service is currently performing another operation like join or leave.

`IN a{sv} `options``: |

### The ChangeLoginPolicy() method

    ChangeLoginPolicy (IN  s     login_policy,
                       IN  as    permitted_add,
                       IN  as    permitted_remove,
                       IN  a{sv} options);

Change the login policy and/or permitted logins for this realm.

Not all realms support all the various login policies. An error will be returned if the new login policy is not supported. You may specify an empty string for the `login_policy` argument which will cause no change in the policy itself. If the policy is changed, it will be reflected in the "LoginPolicy" property.

The `permitted_add` and `permitted_remove` arguments represent lists of login names that should be added and removed from the org.freedesktop.realmd.Kerberos:PermittedLogins property.

`options` can contain, but is not limited to, the following values:

- `operation`: a string identifier chosen by the client, which can then later be passed to Cancel() in order to cancel the operation

- `groups`: boolean which if set to `TRUE` means that the names in `permitted_add` and `permitted_remove` are group names instead of login names.

This method requires authorization for the PolicyKit action called `org.freedesktop.realmd.login-policy`.

In addition to common DBus error results, this method may return:

- `org.freedesktop.realmd.Error.Failed`: may be returned if the policy change failed for a generic reason.

- `org.freedesktop.realmd.Error.Cancelled`: returned if the operation was cancelled.

- `org.freedesktop.realmd.Error.NotAuthorized`: returned if the calling client is not permitted to change login policy operation.

- `org.freedesktop.realmd.Error.NotConfigured`: returned if the realm is not configured.

- `org.freedesktop.realmd.Error.Busy`: returned if the service is currently performing another operation like join or leave.

`IN s `login_policy``: | the new login policy, or an empty string
`IN as `permitted_add``: | a list of logins to permit
`IN as `permitted_remove``: | a list of logins to not permit
`IN a{sv} `options``: | options for this operation

## Property Details

### The "Name" property

    Name  readable   s

the realm name This is the name of the realm, appropriate for display to end users where necessary.

### The "Configured" property

    Configured  readable   s

whether this domain is configured and how If this property is an empty string, then the realm is not configured. Otherwise the realm is configured, and contains a string which is the interface that represents how it was configured, for example org.freedesktop.realmd.KerberosMembership.

### The "SupportedInterfaces" property

    SupportedInterfaces  readable   as

Additional supported interfaces of this realm. This includes interfaces that contain more information about the realm, such as org.freedesktop.realmd.Kerberos and interfaces which contain methods for configuring a realm, such as org.freedesktop.realmd.KerberosMembership.

### The "Details" property

    Details  readable   a(ss)

informational details about the realm Informational details about the realm. The following values should be present:

- `server-software`: identifier of the software running on the server (e.g. `active-directory`).

- `client-software`: identifier of the software running on the client (e.g. `sssd`).

### The "RequiredPackages" property

    RequiredPackages  readable   as

prerequisite software Software packages that are required in order for a join to succeed. These are either simple strings like `sssd`, or strings with an operator and version number like `sssd >= 1.9.0`

These values are specific to the packaging system that is being run.

### The "LoginFormats" property

    LoginFormats  readable   as

supported formats for login names Supported formats for login to this realm. This is only relevant once the realm has been enrolled. The formats will contain a ``U`` in the string, which indicate where the user name should be placed. The formats may contain a ``D`` in the string which indicate where a domain name should be placed.

The first format in the list is the preferred format for login names.

### The "LoginPolicy" property

    LoginPolicy  readable   s

the policy for logins using this realm The policy for logging into this computer using this realm.

The policy can be changed using the #ChangeLoginPolicy() method.

The following policies are predefined. Not all providers support all these policies and there may be provider specific policies or multiple policies represented in the string:

- `allow-any-login`: allow login by any authenticated user present in this realm.

- `allow-realm-logins`: allow logins according to the realm or domain policy for logins on this machine. This usually defaults to allowing any realm user to log in.

- `allow-permitted-logins`: only allow the logins permitted in the "PermittedLogins" property.

- `deny-any-login`: don't allow any logins via authenticated users of this realm.

### The "PermittedLogins" property

    PermittedLogins  readable   as

the permitted login names The list of permitted authenticated users allowed to login into this computer. This is only relevant if the "LoginPolicy" property contains the `allow-permitted-logins` string.

### The "PermittedGroups" property

    PermittedGroups  readable   as

the permitted group names The list of groups which users need to be in to be allowed to log into this computer. This is only relevant if the "LoginPolicy" property contains the `allow-permitted-logins` string.