Tag: <configuration> - Device Specific Configuration Setting

Definition

The <configuration> tag is used to tell the PxM Platform some device specific information that the PxM Platform uses internally when running tasks.

This tag has the following attributes:

Parameters

  • fieldname (str): The name of the configuration item being set.

  • fieldtype (system, device): The type of configuration item being set. system means configuration that is about the PxM Platform itself and device means configuration that is about how the PxM Platform should handle a device. The vast majority of configuration tags are device.

  • value (str): This is the value to assign to the named configuration field. This is a string but it can also be an integer depending on the field being set.

There are a number of configuration field names that can be set.

  • management_system_rolename
  • management_system_breakglass
  • accountname_len
  • username_policy
  • password_len
  • password_chset
  • password_chset1
  • password_chset2
  • password_chset3
  • password_chset4
  • password_pattern
  • share_directory
  • share_root

management_system_rolename

This defines the accesstoken (aka role) that should be assigned to the osirium1 account when added to a device, if the device has the control account set to Managed during device provision.

1
<configuration fieldname='management_system_rolename' fieldtype='device' value='readwrite'/>

If not set, the PxM Platform will default to a management_system_rolename value of readwrite.

However, if there is no accesstoken defined with the name readwrite then the template will fail.

management_system_breakglass

This defines the accesstoken (aka role) that should be assigned to the osiriumbg (breakglass) account when added to a device, if the device has the control account set to Managed*.

1
<configuration fieldname='management_system_breakglass' fieldtype='device' value='readwrite'/>

Again, if not set, the PxM Platform will default to a management_system_breakglass value of readwrite. However, if there is no accesstoken defined with the name readwrite then the template will fail.

accountname_len

This defines the maximum length of an account name that can be defined on a device. If the length of an account that the PxM Platform needs to create is greater than this value, then the last 6 characters of the account name are removed and replaced with a hash based on the full original account name that was required. This allows for maximum account names to be handled by the PxM Platform but the accounts still contain the majority if not all of the username, linking the account back to the user.

1
<configuration fieldname='accountname_len' fieldtype='device' value='20'/>

accountname_policy

This defines if Managed accounts to be created on a device should be created with all lowercase characters.

Some devices require this.

1
<configuration fieldname='accountname_policy' fieldtype='device' value='lowercase'/>

password_len

This defines the maximum length of a password on the device.

1
<configuration fieldname='password_len' fieldtype='device' value='15'/>

password_chset

This is the simplest way to define a character set to be used when creating new device account passwords. The PxM Platform will randomly select the number of characters defined by 'password_len' (see above) from the list of characters defined by 'password_chset'.

1
Configuration fieldname="password_chset" fieldtype="device" value="abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWZ0123456789"/>

password_chset1-4

This is a more advanced method of defining a password character set. the PxM Platform will pick at least one character from each of the password_chset1-4 groups. This allows for a password policy to be defined. the PxM Platform will continue to select characters from each of the groups as it builds the full length password as defined by 'password_len'.

1
2
3
4
<configuration fieldname='password_chset1' fieldtype='device' value='abcdefghijklmnopqrstuvwxyz'/>
<configuration fieldname='password_chset2' fieldtype='device' value='ABCDEFGHIJKLMNOPQRSTUVWZ'/>
<configuration fieldname='password_chset3' fieldtype='device' value='0123456789'/>
<configuration fieldname='password_chset4' fieldtype='device' value=',$()[]{}_-+='/>

password_pattern

The recommended method of generating passwords. A regular expression is defined in the value attribute, and the PxM Platform generates a password to fit the regular expression. The regular expression overrides the 'password_len' configuration if it is present, and should not be used in conjunction with any password_chset tags.

As shown below, the regular expression defines the character sets and also a variable length.

Once processed the resulting password is shuffled so it no longer resembles the regular expression supplied in the template.

1
<configuration fieldname='password_pattern' fieldtype='device' value='[a-z]{2}[0-9]{2}[A-Z]{2}[$%^*]{2}[a-z0-9-A-Z$%^*]{4-7}'/>

The above regular expression breaks down into:

RegEx Component Meaning
[a-z]{2} 2 lowercase alphabetic characters (characters can be repeated)
[0-9]{2} 2 digits (digits can be repeated)
[A-Z]{2} 2 uppercase alphabetic characters (characters can be repeated)
[$%^*]{2} 2 symbols from the range $%^* (symbols can be repeated)
[a-z0-9-A-Z$%^*]{4-7} minimum 4, maximum 7 characters from the range a-z0-9-A-Z$%^* (characters can be repeated)

share_directory and share_root

In the the PxM Platform release Windows templates, there are two configuration items that are used as part of the file copy mechanism.

These, like all configuration items, can be used as substitutions anywhere in an the PxM Platform template. This is exactly how these two Windows file copy parameters are used.

More info here: :ref:windows-smb-get.

1
2
<configuration fieldname='share_directory' fieldtype='device' value='%SystemDrive%\osirium'/>
<configuration fieldname='share_root' fieldtype='device' value='osirium_'/>

Adding Custom Configuration Items

You can add any configuration items you like to a template. They are then available to be used anywhere that substitutions can be used within a template. Configuration items are set in the template and remain hidden from view, whereas a task input configuration fixed string is set and can be viewed in the Web Management Interface.

You can add configuration items to any split template, like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<?xml version='1.0' encoding='utf-8'?>
<devicetemplate>
   <configurations>
      <configuration fieldname='ad_domain' fieldtype='device' value='hq'/>
   </configuration>

   <tasks>
      ...
   </tasks>

</devicetemplate>

In the above split template file, the configuration parameter called ad_domain is set to the value hq. Any task or message can then use the following substitution to use the domain name, set here to hq.

1
   %(ad_domain)s

Example

The <configuration> tag is always used inside the <configurations> parent tag, like this:

1
2
3
4
<configurations>
   <configuration ... />
   <configuration ... />
</configurations>

Parent Tags

Child Tags

  • None