The restoreusers tool reads an XML file which has been written using the dumpusers tool (see Section 3.13.2.6, “Dumpusers”). The structure of the XML file is defined by the lib/xml/coremedia-userrepository.xsd schema. It contains a nested structure of group elements which contain rules defined for this group and elements representing the members of this group. To provide for membership in multiple groups a userref or groupref element can be used which refers back to a previously defined user or group.

<group id="g13" name="global-manager" contentgroup="true" livegroup="false"
       administrative="false">
  <rule content="/Settings/Meta/Mail" type="CMMail" rights="RMDAP"/>
  <rule content="/Settings/Options/Bundles" type="CMSettings" rights="RMDAP"/>
  <rule content="/Settings/Options/Settings" type="CMSettings" rights="RMAP"/>
  <rule content="/Settings/Taxonomies" type="CMTaxonomy" rights="RMDAP"/>
  <rule content="/Themes" type="CMObject" rights="RMDAP"/>
  <rule content="/Themes" type="CMTemplateSet" rights="RMDAP"/>
  <rule content="/Themes" type="Folder_" rights="RMDAP"/>
  <members>
    <group name="global-site-manager-c" contentgroup="true" livegroup="false"
           administrative="false">
      <rule content="/Sites/Chef Corp." type="CMObject" rights="RMDAPS"/>
      <rule content="/Sites/Chef Corp." type="Folder_" rights="RMDAPS"/>
      <rule content="/Settings/Taxonomies" type="CMTaxonomy" rights="RMDAP"/>
      <members>
        <user id="u10" name="Colin" home="/Home/Colin"/>
        <user id="u9" name="Rick C" home="/Home/Rick C"/>
      </members>
    </group>
  </members>
</group>

For a description of the flags shown at the rights attribute, see Section 3.15.2, “User Rights Management”.

Members are identified by their capid attribute, if given. If no capid is given, the member is identified by name and domain. If no such member is found, a new member is created. Members can only be created in the built-in user repository!

The identified member is updated to the corresponding values in the XML file, such as name, password, home folder and a group's isAdministrative flag. A new home folder is created if the given path does not exist yet.

Please note that the (optional) password attribute is always given unencrypted in the XML file and thus not suited for sensitive data.

<user id="u10" name="Colin" password="mySecretPassword" home="/Home/Colin"/>

Restrictions

Many attributes cannot be changed once a group or user has been created:

• member names, as members are identified by name;

• domain;

• UUID, unless --force-uuids is specified;

• flags isContentGroup and isLiveGroup;

and in addition to that for externally provided users (like from LDAP):

• password;

• UUID;

• members of groups.

If a mismatch is detected, the restoreusers tool exits with an error message. In addition, the tool can only add or change rules (including rules on external groups) and can only add memberships, but cannot remove them.

When a rights rule refers to a non-existent content path, an empty folder will be created at the indicated location, unless the rule's createFolder attribute is set to false. If createFolder is false and the folder does not exist, the rule is ignored on import.

The options have the following meaning:

Parameter	Description
{ -f | --file } file	File where to read the user repository XML from. May be provided as URL.
--force-uuids	Enforces setting UUIDs for existing built-in members. While, by default, existing built-in members will not get a new UUID assigned, you may enforce overriding UUIDs with this option. This option has no effect, if --skip-uuids is given. Override UUIDs With Care If you used member UUIDs in references, your references will become invalid. Mapped UUIDs will be written to output, so that you may adapt the references.
--skip-uuids	Ignores UUID possibly given in user repository XML. Instead, when creating built-in members, random UUIDs will be generated. Implicit Skip on Server Version or Type If the server you are connected to does not support creating members with given UUID (because of type or version, see below), UUIDs will be implicitly ignored. Creating members with UUID is neither supported for versions prior to 2010.1 nor for Live Servers, that is, it is only supported for Content Management Servers 2010.1 and later.
{ -z | --zip } file	Alternatively to the --file option, you can specify a zip file to extract user repository XML files from.
{ -zd | --zip-directory } directory	A subdirectory within the zip file.
-v | --verbose	Toggle verbose output.

Table 3.35. Parameters of restoreusers

Exit Code

On any failure while restoring users, restoreusers will exit with a code different to 0 (zero).