6.5.1. 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 Section 6.5.6, “Synchronizing user.map Data”.

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.


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:

    |  # pipe
    \t # tab
  • If direct reads (using the @direct directive, the following characters should be avoided within passwords:

    & # ampersand
    @     # at sign
    =     # equals
    ?     # question mark
  • 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]


  • 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.

  • 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.

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 nyc_sfo

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

sales secret nyc_sfo sfo