Account Defaults Configuration

From PsiWiki

Contents 1 Work in Progress, do NOT USE this documentation 2 Patch Purpose 2.1 User Visible Behavior Changes 2.2 Typical Deployment Scenario 3 Configuration Syntax 3.1 Required Elements 3.1.1 Accname Syntax 3.1.2 User Syntax 3.1.3 Server Syntax 3.1.4 Jdomain Syntax 3.1.5 Resource Syntax 3.2 Optional Elements 3.2.1 Silent Syntax 3.2.2 Override Syntax 3.3 Method Parse Rules 3.4 Boolean Parse Rules 3.5 Integer Parse Rules 4 Examples 4.1 Simple Network 4.2 Distributed Network 4.3 Complex Network 4.4 Other Networks

Work in Progress, do NOT USE this documentation

This documentation applies to the upcoming patch for handling default account data.

Although not required, this patch is recommended to be used alongside the new password dialog patch as it streamlines the setup process and helps keep from confusing a user in the case a central password (ex. LDAP auth) is changed.

Patch Purpose

When in place, the patch changes the default behavior when launching Psi without an account profile already extablished (ex. first launch). This allows an administrator to package and install a copy of Psi that will use sane account defaults appropriate to the deployment site.

Note that this is a expert/sysadmin level feature intended to ease network deployments of Psi. This is not a feature that a standalone user should ever bother looking at.

User Visible Behavior Changes

Without the patch, Psi would bring up a dialog to create an account and wait for the user to select the name and then press Add. Once this was done, the user would need to setup all the information under the account modification dialogs to connect.

With the patch in place, Psi instead looks into its resource directory for a file called "defaults.xml". If this file is in place, Psi attempts to read this in as an XML document and then proceeds with account creation as the file specifies. If this file is not in place, Psi continues as was the case before the patch.

Typical Deployment Scenario

The system administrator either modifies a standard Psi package to include a custom CA certificate (optional) and the defaults.xml file. The defaults.xml file is configured in such a way to automatically supply all the parameters needed for a user to connect to a Jabber account other than that user's password. When a user first runs Psi, he is shown the usual tips (with the option to disable them at later startups) and a password dialog box for his Jabber password.

Configuration Syntax

Required Elements

Each of these elements is required in this config file. Failure to specify all can result in undesired and unpredictable behavior.

<!DOCTYPE firsttimedefaults>
<firsttimedefaults>
 <accname/>
 <user/>
 <server>
  <jdomain/>
  <resource/>
 </server>
</firsttimedefaults>

Accname Syntax

This element is parsed according to the global #Method Parse Rules. It supports no additional attributes at this time.

The Accname attribute is used to specify what name Psi should use for the new account. This is displayed on the contacts list and in the account selection dialog, so it should be formatted so it shows reasonably well in the client.

<accname method=""/>

User Syntax

This element is parsed according to the global #Method Parse Rules. It supports no additional attributes at this time.

The user element is used to determine the part of a JID that comes before the @ symbol.

<user method=""/>

Server Syntax

This element acts as a container for server/connection related elements. It also holds some connection related attributes. All attributes on this element are parsed according to the global #Boolean Parse Rules.

• The ssl attribute specifies if the connection should encrypted via the ssl protocol.
• The reconn attribute specifies if the connection should be re-established if it is lost.
• The autoconn attribute specifies if the client should automatically connect when Psi is launched.
• The allowplain attribute specifies if the connection should be allowed to use a plaintext password. As this is a really bad idea over an unencrypted connection, the parser may attempt to keep this from being used without ssl on accident. Just don't do it.

<server ssl="" allowpain="" autoconn="" reconn="">
</server>

Jdomain Syntax

This element is parsed according to the global #Method Parse Rules. It supports no additional attributes at this time.

The jdomain element is used to determine the part of a JID that comes after the @ symbol.

<jdomain method=""/>

Resource Syntax

This element is parsed according to the global #Method Parse Rules. It supports a priority attribute parsed according to the #Integer Parse Rules.

• The priority attribute specifies the priority value that should be used for the connection.

The resource element is used specify the resource name of the Jabber connection.

<resource method="" priority=""/>

Optional Elements

The elements silent and override are optional. If used, all required atrributes for each element must still be followed. Their positions in the xml tree are shown below.

<!DOCTYPE firsttimedefaults>
<firsttimedefaults>
 <silent/>
 <server>
  <override/>
 </server>
</firsttimedefaults>

Silent Syntax

This element supports no attributes.

If this element is present, silent mode is enabled (recommended). Silent mode keeps Psi from showing the user the account dialog once it has created the account. Without this option enabled, Psi will show the account dialogs.

If for some reason this is used without the recommended patch above, this might be useful to allow users to enable saving a password. If the password dialog patch is used, other than some odd required proxy situations, this probably won't do any end users any good, but might be nice to save a few clicks when configuring the defaults.xml for suitable values on your network.

Override Syntax

This element is parsed according to the global #Method Parse Rules. It supports a port attribute parsed according to the #Integer Parse Rules.

• The port attribute specifies the tcp port that should be used for connection to the Jabber server.

The override element is used to determine the part of a JID that comes before the @ symbol.

<override method="" port=""/>

Method Parse Rules

Here is where things get tricky. The method type is very flexible to allow for many possible deployment options. Due to this flexibility, this type also is a little complicated to setup with many different options:

• method="const" -- The text supplied for the element is taken as a literal value. This works well for static data like the account name or server addresses.

<element method="const">ThisLiteralValueUsed</element>

• method="env" -- The text supplied for this element is taken as the name of an environment variable to retreive the value of. If all else fails, an administrator can add an environment variable through a login script to supply the correct value to a user as a parameter.

<element method="env">ENVIRONMENT_VARIABLE</element>

• method="systemuser" -- Attempts to retreive the username of the currently logged in user from the system. Any value supplied to the element is ignored.

<element method="systemuser"/>

• method="hostname" -- Returns the complete hostname of the system as returned by the gethostname system call.

<element method="hostname"/>

• method="hostdomain" -- Returns the domainname of the system as returned by the gethostname system call after stripping off the host. This should just return the domain the system is on.

<element method="hostdomain"/>

• method="host" -- Returns the host of the system as returned by the gethostname system call after stripping off the domain portion. This should just return the host itself.

<element method="host"/>

• method="domainname" -- Returns the domainname of the system as returned by the getdomainname system call. Note that on my Linux machine, this is actually the NIS name.

<element method="domainname"/>

This feature set is designed to be easily expandable, so additional types should be simple to add. In addition, there are some post-processing options that are available to all the above method types.

Appends and Prepends (both allowed simultaneously):

• prefix="constant" -- Prepend the constant supplied to the beginning of the string.

<element method="systemuser" prefix="KU"/>

• postfix="constant" -- Append the constant supplied to the end of the string.

<element method="systemuser" postfix="a"/>

Capitalzation:

• caps="all" -- Force the returned string to uppercase.

<element method="hostname" caps="all"/>

• caps="none" -- Force the returned string to lowercase.

<element method="fromdomain" caps="none"/>

• caps="first" -- Force the first letter of the returned string to uppercase and leave the rest alone.

<element method="host" caps="first"/>

Boolean Parse Rules

All boolean values must match case exactly.

The only available method of specifying these values:

<element attribute="true"/>
<element attribute="false"/>

Integer Parse Rules

All integer values supported are actually unsigned integers in decimal notation.

No significant bounds checking or validity checking are provided. Make sure you actually specify valid numbers (this is an expert level feature, remember?).

Examples of valid integer values:

<element attribute="6"/>
<element attribute="5224"/>

Examples of invalid integer values:

<element attribute="0x3F"/>
<element attribute="0b1101"/>
<element attribute="-5"/>

Examples

Simple Network

<!DOCTYPE firsttimedefaults>
<firsttimedefaults>
 <silent/>
 <accname method="const">Business Name</accname>
 <user method="systemuser"/>
 <server ssl="true" allowplain="true" autoconn="true" reconn="true">
  <jdomain method="const">jabber.businessdomain.com</jdomain>
  <resource method="const" priority="4">Desktop</resource>
 </server>
</firsttimedefaults>

Notice how the only dynamic data used is the username. There are a few potential problems with this approach, for example logging into two account setup with these settings at the same time will have a conflict with the resource name.

Distributed Network

<!DOCTYPE firsttimedefaults>
<firsttimedefaults>
 <silent/>
 <accname method="const">Business Name</accname>
 <user method="systemuser"/>
 <server ssl="true" allowplain="true" autoconn="true" reconn="true">
  <jdomain method="hostdomain" prefix="jabber."/>
  <resource method="host" caps="first" priority="4"/>
 </server>
</firsttimedefaults>

From the simple case, we now automatically generate an Resource name based on the hostname of the machine.

We also now configure the JID based on the system hostname. For example, a system with a hostname of machine64.sales.corpname.com will now show a JID in the form of user@jabber.sales.corpname.com. Another machine at machine42.engineering.corpname.com would thus get a JID of user@jabber.engineering.corpname.com. Obviously defaults will be wrong if a company laptop first launches Psi from outside their controlled network, etc.

Complex Network

<!DOCTYPE firsttimedefaults>
<firsttimedefaults>
 <silent/>
 <accname method="const">Business Name</accname>
 <user env="XMPPUSER"/>
 <server ssl="true" allowplain="true" autoconn="true" reconn="true">
  <jdomain method="hostdomain"/>
  <resource method="host" caps="first" priority="4"/>
  <override method="hostdomain" prefix="jabber." port="5223"/>
 </server>
</firsttimedefaults>

In this case, there is the additional complexity of system usernames not directly matching between Jabber and the system. There is no possible way for Psi to understand any custom mappings, so the administrator must supply the JID that matches. In this example, that is done by setting the XMPPUSER environment flag.

In this case, the JIDs are based on the subdomain and don't have the servername as part of the JID. Psi doesn't support the srv records yet, so we help it by manually specifying the servername to use. In this case, we have followed a pattern of the servername being the same as the JID except for jabber prepended, but a login script could provide a servername just like the username method we use.

Other Networks

If you have a significant usage example that's missing here, please add it. If you can't figure out how to adapt these options to your network, please submit your situation to the Psi Development List.