Auto-assign

Introduction: What is Automatic Assignment (Auto-Assign)?

Auto-Assign means that new clients will be placed into a specific group and getting this group's configuration immediately, rather than being placed into the default "Unassigned" group without any configuration and waiting for the system administrator to add them to a group.

Autoassign allows for full automation of a NoTouch rollout:

1. New clients will contact NoTouch Center using the usual methods such as the tcmgr DNS host name
2. NoTouch Center will decide which group the client will be put into based on "Auto-assign" criteria
3. The clients will receive a configuration immediately afterwards

Technically speaking, whenever a new client announces itself to NoTouch Center first time, NoTouch Center will iterate through all groups, evaluate all criteria until a match is found.

Please note that auto-assign is happening in the background, no matter if somebody is logged into the Web GUI or not. NoTouch Center will generate log messages with precise information what client was put into which group and why. If however the administrator is logged in, NoTouch Center will not automatically reload the GUI tree for performance reasons - Simply click on "Manage" to reload the management view and get a reloaded tree pane.

For the impatient: Simple scenarios

I want to add all clients of IP subnet 192.168.26.0/24

1. Click on your target group
2. Enter 192.168.26.0/24 into the "Network address/Subnet mask" parameter

Provided you have not modified the default values of the master switches, autoassign will happen with the next "first-timer" device announcing itself.

I want to add all 'WonderPC' PCs

1. Click on your target group
2. Enter WonderPC.* (substitute WonderPC with your favorite PC brand) into the "System Product" parameter

Note: This depends on the hardware vendor filling in the correct values into the DMI BIOS. Some companies don't seem to get it, alas.

Auto-Assign group configuration

The configuration parameters for Auto-assign can easily be accessed by simply clicking on the group and scrolling to "Automatic assignment".

Group-based master switch

Every group has a parameter "Automatic assignment" that is "on" by default. Only if the parameter is on, this group is part of Auto-assign. If it is off, the group will be skipped in any Auto-assign evaluation and no clients will ever be auto-assigned to that group.

Unique group key

One way - and actually a very precise one - of auto-assign is using group keys. For each group NoTouch Center will generate a unique, somewhat memorable group key. This key can be entered into a NoTouch client's First Time Wizard providing precise and fool-proof auto-assignment that is based solely on this key, not on other criteria like network addresses etc.

In other words, you can hand the key out to your people that are supposed to install NoTouch and you are guaranteed the clients will be auto-assigned into the correct group, no relying on correct network addresses or DMI BIOSes. A scenario where this would come handy is a service provider that hands the key over to a customer, and has all their machines going into one group, and another customer would get a different.

Group keys should be treated as secret as they allow somebody to connect a new NoTouch instance to NoTouch Center and fetching the group's configuration.

On the client, by clicking on "Central Management" on the left you get to the "Central Management" dialog. Enter the group key into the "Group assignment key" field to have this client being put into this group.

Client Criteria / Status Values

NoTouch endpoints send certain pieces of hardware and environment information to NoTouch Center, so-called "status values". Examples of status values are network configuration items like IP address or MAC address, as well as DMI-BIOS information like System Product name. These status values can be used for autoassign. Potential uses are (not limited to) autoassign based on:

• Subnets
• Hardware
• Location/Ownership

How does this work?

• All status values are evaluated using "Regular Expressions" (regex). The Java Regular Expression engine will match the "pattern" (i.e. your configured value in these parameters) to the actual value, and decide if there is match. Java Regular Expressions are fairly compatible to Perl-style regular expressions. Unless you really do exotic stuff, you should not run into any issues.
• NoTouch Center will sequentially try to match each parameter. If there is a match, the Autoassign will happen, no more parameters will be tried.
• Do not rely on a specific sequence. Simply treat it as an "or"-condition without a sequence. If you need more complex conditions, see below.

The only exception to the regex matching is the "Network address/Subnet mask" parameter. It will be matched using classic subnet rules:

• An IP address of 192.168.17.5 would match for instance 192.168.17.0/24, but not e.g. 10.0.0.0/16
• 0.0.0.0/0 would match any host, 0.0.0.0/32 would match no host

Regular expression (regex) basics

A . (dot) matches any character, but just one. If you add the * (asterisk) quantifier, it will match zero or more. If you however use the + (plus) quantifier, it will match a character one or more times. The ? (question mark) quantifier matches once or zero times. A character class can be defined with [], e.g. [a-z] means only a lowercase letter would match. Again, add a quantifier to denote if more of them should be allowed to match. A simple "or" can be expressed with | (pipe symbol). The ^ means start of line, the $ denotes end of line. We do not make use of any group capturing, just in case you stumble upon these while researching regular expressions.

Note for all the DOS/Windows/Shell guys: Keep in mind that the well-known Windows * wildcard alone does not mean anything in regular expressions. The correct equivalent would be .* (dot asterisk without a space in between)

More on regular expressions:

• Regular Expressions on Wikipedia [1]
• Java Regular Expressions [2]

Customizing

As if the aforementioned mechanisms weren't flexible enough, NoTouch Center still offers more customization potential:

User-defined status values

There are more status values than the ones that have corresponding pattern parameters. Should you really want to evaluate such status values for auto-assign, you can add up to three such values. The parameters "User-defined status value: pattern 1" to 3 allow to store both the database name of the status value and the pattern used to match against the actual value, separated by colon (:).

For example, NoTouch Clients send detailed CPU information in the CPUINFO_MODEL status value. Say, you want to match VIA CPUs, you may use this for one of the user-defined parameters:

  CPUINFO_MODEL:VIA.*

We suggest to look into the STATUSVALUE database table to see what values your clients deliver and decide accordingly.

Custom condition expression

The parameter "JavaScript condition expression" allows to use customer-defined condition expressions to replace the default sequential "or" logic. If this parameter is used, than a boolean variable will be created for each of the criteria parameters, its true/false value reflecting if the criteria test was successful or not. These variables can be used in a JavaScript/ECMAScript expression that results in a final boolean value, indicating if the auto-assign should happen or not.

NoTouch Center uses Java's builtin JavaScript/ECMAScript scripting engine Nashorn (Java 8) or Rhino (Java 7) to evaluate the expression. Using this parameter and evaluating the condition adds additional load on the server, as the scripting engine has to be used whenever a new client announces.

A valid expression would be:

  LOCATION || (VIDEOPCI && SYSPROD)

This would mean that either the location field, or the Video-PCI-IDs and the System Product value together would result in a positive match.

These are the usable values:

• LOCATION. Refers to the "Location" field.
• DESCR. "Description" field.
• IP. "Internal IP address" field.
• GW. "Gateway adress" field.
• HOSTNAME. "Hostname" field.
• WLANSSID. "WLAN SSID" field.
• VIDEOPCI. "Video PCI ID" field.
• NETWORKPCI. "Network PCI ID" field.
• PRINTERUSB. "Printer USB ID" field.
• SYSPROD. "System Product" field.
• SYSSER. "System Serial" field.
• SYSVEND. "System Vendor" field.
• CUSTOM1, CUSTOM2, CUSTOM3. The "User-defined status value" fields.

Scripting

Taking the customizing even further, you can supply your own auto-assign functionality with a script using the Scripting interface. You may place a script named "autoassign" into the NoTouch Center script folder. If no auto-assign happens because of the parameters, then the script will be called.

NoTouch Center supplies all of the client's mac address in a variable named "id". The script can parse it and make a decision on where to put the device. NoTouch Center expects the script to set a variable named "result" that contains the "COID" value of the target group (from the CONFIGOBJECT database table).

Predefined auto-assigning

NoTouch Center (from 4.2.195 on) allows you to assign clients to groups based on their MAC addresses via a pre-supplied text file. For instance, you can use this to export MAC addresses and target groups from an asset management database, if you don't want to use the scripting feature for this. An additional feature of this method is to set the host name and arbitrary other client based parameters.

You can supply a file named assign-predef.txt in the etc/ directory of your NTC installation. The file should be in CSV format, with one line describing one client. The format is

     mac-address,target group,host name,further parameter 1, further parameter 2,...

The fields in detail are:

• mac-address. A future client's MAC address. May be with colons or without colons, upper or lower case.

• target group. An id or name. You may even specify id:X or name:X to clarify. We suggest to use the internal id values (COID) since they are unique. If you use names, make sure only one group with that name exists, otherwise the system will not perform the auto-assign.

• host name. If not empty, this will be set as both the DNS hostname (NET_HOSTNAME),

• further parameter X. Multiple key/value pairs. The key refers to the code name of a parameter. For instance, SYS_USER=Frank Johnson would be a valid entry. Since this format makes special use of the , and = characters, you must escape them if you want to use them. &#CO# refers to a comma, &#CO# to an equals sign. Thus, SYS_USER=Frank Johnson&#CO# CEO would lead to the parameter being set to Frank Johnson, CEO.

Example

Consider the following case: If a host with the MAC address of 00:0c:29:6e:48:b0 connects, it should be placed in the group id 8 and its name should be set to "franktc". Furthermore we'd like to set the system owner description parameter to "Frank Fox, Tester". This would be accomplished by the following line in the predefine file:

      00:0c:29:6e:48:b0,id:8,franktc,SYS_USER=Frank Fox&#CO# Tester

Auto-Reassign

Auto-Reassign means that on every announce even of well-established clients the auto-assign criteria will be checked and potentially a client will be moved into a different group.

This functionality is deactivated by default and needs to be actived explicitly. Activating this feature places additional load on the server!

Settings

In the NoTouch Center Settings dialog you can find a sub-header "Automatic assigning to groups". Please see here for more information: NoTouch Center Settings#Automatic assigning to groups

Legacy NoTouch Center 4.1.28 and earlier versions

The Auto-assign functionality has changed significantly in NoTouch Center 4.1.320 and above. These are the instructions for NoTouch Center 4.1.28 and earlier:

Without any further setting, new clients will be put into the "Unassigned" group and it is up to the system administrator to add them to a group. If you are serious about auto-assign, you should update your NoTouch Center installation as the available options in legacy NoTouch Center 4.1.28 and earlier were very much limited on contrast to what is available today.

A very easy way of defining a per-subnet allocation would be based on "gateway". The gateway is almost equivalent to subnet address but saves both the customer and the software the bitmask calculation.

1. Type the "gateway address" of a group into the Group settings / Networking / Gateway parameter. That is the "filter expression". It means that a client machine with the same gateway address (usually assigned by DHCP) will be put into the group.
2. Go into the NoTouch Center settings and type in "AutoassignGW" without the quotes into "Active Agents".
3. Restart NoTouch Center.

Note: When machines are assigned automatically, this happens in the background and the GUI may not reload (because it is a background job that doesn't reload your browser window). This doesn't matter if you repurpose 10000s of machines, but you should know when you test it out and sort of wait for it.