6.6.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.6.7, “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.

    Version Support: 5.3.0

    The rules for passwords were updated to support quoting.

    • Quotes ' and double quotes " are now 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

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

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