Adding aliases for usernames

In some scenarios, a particular user wants to print a job but his/her username has been changed for various reasons and it is reflected in PaperCut now as a different username. Examples of why the username may have changed:

  • two networks/domains/servers have different naming conventions. e.g. for user, John Smith, one network uses the convention “j.smith” while the other uses “jsmith”
  • for some policy reasons, the format of usernames has changed and you want to allow forgetful users to log in with their old name.
  • Unix has strict requirements for usernames, (IEEE Std 1003.1–2001), where the only valid characters are letters, digits, underscores, full stops, at-signs, dashes (but not start with a dash) and having $ at the end. So when printing on a Unix server, it can sanitize the username, such as converting an apostrophe into an underscore and then recording in PaperCut as a different user when one really wants it to be the same user.
  • Print jobs are coming from an ERP or mainframe system where their usernames are different than in their other network.
  • Print jobs coming from some software packages may use the “application username” and not the users’ network username used by PaperCut. e.g. this can occur in some SAP configurations.

What can one do?

To work around this problem PaperCut allows users to have a list of aliases for their username. There are three options available:

  1. Automatically sync via AD/LDAP
  2. Update and read aliases via the web services API or server-command utility.
  3. Set up aliases using a text file.

Sync aliases using AD/LDAP

To set up the automatic sync of aliases using AD/LDAP, you will need to enable Username Aliasing via Options → Advanced

Once Username Aliasing has been enabled, you will see a new text field on the User Details page.

This information can be automatically imported from Active Directory or LDAP during the overnight sync. Once Username Aliasing is enabled, an option to enter an AD/LDAP field name appears under Options → User/Group sync. Any valid Active Directory or LDAP user field can be chosen to import this information e.g. employeeNumber, employeeID, otherLoginWorkstations.

Once this has been set, information from the Active Directory or LDAP field will be imported every night as username aliases. For more information on user group synchronization see the section called “User and Group Synchronization”.

Update aliases using web services API or the server-command utility

The API allows you to update the username-alias property using the setUserProperties() and setUserProperty() methods, or set-user-property subcommand when using the server-command utility.

You can also obtain the value of the user alias using the corresponding get methods or subcommand

Text file option

The previous methods allow a user to have a single alias. If users have multiple aliases (or the methods above don’t work for you) then use the text file option.

Note that users can have an alias created by the methods described above and additional aliases defined in the text file described here.

So John O’Hare (username “john_o_hare”) can have username aliases of “johnohare”, and “johare”. The aliases information is kept in a file,


and can be created based on the provided template file,


For example on Windows:

  • Go to the directory of C:\Programs\PaperCut NG\server\data\conf
  • Run Notepad or your favorite text editor on the file username-aliases.txt.tmpl
  • Add the following lines to the end:
        johno'hare: john_o_hare
        johare:     john_o_hare
  • Save file as username-aliases.txt

The format of the alias file is:

aliasname1: username1
aliasnameA: username2
aliasnameB: username2

where aliasname is mapped to username in the system database. A user may have multiple aliases. In this example, username2 is known both as aliasenameA and aliasnameB. The separator between aliasname and username can be “:”, “=“ or tab.

Note that it is important to make sure that all the alias names are unique, and don’t clash with the usernames or any alias names created by the previous methods.

At what level is the alias applied?

The username aliases are applied at the following levels:

  • User login to the web interface, client popup authentication, or release station login.
  • Print jobs arriving in the print queues under the alias name.

Note: If you add “admin” as an aliased user, you may not be able to access the PaperCut Administration Console.

What happens if the username does not exist in the list of aliases?

If a username does not match in the list of aliases it’s assumed the user is a standard username. If the user is new to the entire system it will be managed as a new user account and automatically created in PaperCut as per your new user rules defined under the groups section (group level initial user creation rules). For this reason, you should take care to ensure your alias list is current and up-to-date.

Categories: How-to Articles, User Management, Authentication

keywords: ERP, mainframe, SAP, lookup, look-up, map, translate, UNIX