Tungsten Clustering

user.map File Format

The current user.map file is located within the tungsten-connector/conf directory within an active installation. The file should be synchronized across all the servers within a dataservice. For more information on methods for keeping the file in sync, see "connector-authentication-sync".

The user.map file contains the usernames and passwords for each user that connects to the connector and the downstream MySQL server, and these entries are required for authentication. If an entry does not exist within user.map users will be unable to connect to MySQL through the connector.

important

All the users that require access to your MySQL servers through the Tungsten Connector must have an entry in the user.map. Without this information, the Tungsten Connector has no way of providing an onward connection to a MySQL server.

The rules for the format of the file are as follows:

Anything after a # (hash) symbol are interpreted as comments and ignored. For example:
```
# This line is a comment
```
The following character cannot be used as the username, password or dataservice values:
```
space
|  # pipe
         # tab
```
Using the - (hyphen) character as a password indicates that there is an empty or no password ("") for the specified user.

The basic format for user entries within the user.map is:

username password servicename [affinity]

Where:

username - the username to be used for authentication.
The username also provides hooks into additional options; see @script, @direct, @hostoption.
password - the password to be used for authentication.
- Quotes ' and double quotes " are supported in the user.map password.
- If there's a space in the password, the password needs to be surrounded with " or ':
```
"password with space"
```
- If there's one or several " or ' in the password without space, the password doesn't need to be surrounded
```
my"pas'w'or"d"
```
- If the password itself starts and ends with the same quote (" or '), it needs to be surrounded by quotes.
```
"'mypassword'" so that the actual password is 'mypassword'.
```
As a general rule, if the password is enclosed in either single or double quotes, these are not included as part of the password during authentication.
servicename - the name of the dataservice or composite service to which this username/password apply.
affinity - if the servicename is a composite service, the affinity identifies which service should be preferred for reads.
The affinity feature routes both reads and writes when using a Composite Active/Active topology.
The read affinity setting supports multiple dataservices with ordering and exclusion.
You may fine-tune the affinity by specifying an ordered list of dataservice names.
- The affinity string is an ordered list of dataservice names, separated by commas, where the first dataservice entry will be the one used by default. If the first dataservice in the list is not available, the connector will use the next one listed, and so forth.
- Dataservices not specified in the list, if any, will be used last and randomly.
- It is also possible to exclude one or more dataservices by adding a hyphen ("-") in front of the dataservice name.

For example, to configure the user sales with the password secret to use MySQL servers within the alpha dataservice:

sales secret alpha

To configure a user that has no password:

sales - alpha

To configure a user within a composite service:

sales secret global

To configure a user within a composite service, preferring the east service for read-only connections:

sales secret global east

The deployment used in the examples below consists of a composite dataservice global, with four member dataservices (i.e. one cluster per site): east, west, north and south.

For example, to exclude site south from servicing read requests:

sales secret global east,west,north,-south

The above affinity string "east,west,north,-south" will try east, then west, then north. If none of the first three are available, a connection request would not succeed since south has been excluded by the negation ("-").

In the following example, dataservices north and south would be available as random candidates if the first two (east and west) were unavailable:

sales secret global east,west