ArcGIS Server Java Help - Managing GIS Server user accounts on Linux/Solaris

User management of ArcGIS Server on Linux/Solaris is different from ArcGIS Server on Windows. On Linux/Solaris, ArcGIS Server has different levels of user accounts:

OS-level user accounts—Accounts used by the ArcGIS Server at the operating system level
Local GIS Server users—Network LAN users connecting via TCP/IP (DCOM) to ArcGIS Server machines

Overview of ArcGIS Server accounts on Linux/Solaris

The illustration below lists the accounts that are used to administer ArcGIS Server on Linux.

OS-level user accounts—Accounts used by ArcGIS Server at the operating system level

superuser—Installing ArcGIS Server on Linux or Solaris requires superuser privileges. This is only required at the time of install, uninstall, and ServerConfig.
There are several reasons to require superuser privilege. The superuser/root launches the installation, uninstallation, or ServerConfig, and in the background, it completes the following procedures:
- Creates the agsadmin, agsuser, and ArcGIS Server owner accounts (creation of the ArcGIS Server owner account through setup is optional).
- Installs the ArcGIS Server Enterprise Core Service components to run under multiuser mode. Some of the files need to be installed under the /etc folder, which requires superuser privileges.
- Sets the GIS server processes to autostart when machine is rebooted or started up.
- Assigns ports to various processes. One of the most important factors is that ArcGIS Server uses the Distributed Component Object Model (DCOM) as a distributed computing mechanism. DCOM requires the use of port 135. Processes that listen on ports less than 1024 need to be run as the superuser.
install owner—This is the user you input during the installation. It owns the <ArcGIS Server Installation directory>/arcgis folder. It owns the SOM and SOC processes. You can use an existing account, or the ArcGIS Server installation will create it for you. On Linux/Solaris, the Install owner = the SOM account = the SOC account.
agsadmin and agsuser—These two OS user accounts are created at the time you install either the Server Object Manager (SOM) or the Server Object Container (SOC) component. The default password is "agsadmin" for agsadmin and "agsuser" for agsuser. It is strongly recommended that you change the password immediately after the installation of ArcGIS Server

All users accounts that connect to, administer and consume the services offered by ArcGIS Server are virtual user accounts that exist only within the application scope of ArcGIS Server. The underlying DCOM infrastructure, however, needs physical accounts to impersonate incoming user identities for certain operations such as activation and access to physical resources.

Creating these two physical OS users—agsadmin and agsuser—allows ArcGIS Server to map virtual users (Local GIS Server users created in ArcGIS Server Manager) to an existing Linux/Solaris user account. Each of these two physical user accounts represents the corresponding authorization groups (agsadmin or agsusers) to which the virtual user account belongs.

Local GIS Server users—For local connections

For local connections, ArcGIS Server on Linux/Solaris handles requests and responses in a secure environment as described in the diagram below:

ArcGIS Server on Linux/Solaris has an embedded Sun Directory Server that gets installed with the SOM component. ArcGIS Server uses this directory server to maintain a repository of users that can access ArcGIS Server over a local connection.

There are two levels of user access: user (belongs to the agsuser group) and administrative (belongs to the agsadmin group). At runtime, when a user request comes into the system, the SOM uses the directory server to authenticate the user and determine what group the user belongs to: agsusers or agsadmin. It then maps the user to the appropriate OS-level account. The request is either accepted or denied based on the user's membership in either of these accounts.

Local GIS Server user lists

Local GIS Server users are managed and maintained by the SOM through a Sun One Directory Server that gets installed with the server. ArcGIS Server uses this directory server to maintain a repository of users that can use and manage ArcGIS Server over a local connection. When ArcGIS Server is uninstalled, the directory server is wiped clean, and all user information gets deleted. These are not OS-level accounts. You can manage these users through ArcGIS Server Manager.

admin: This user is created during the installation process. It has an administrator (agsadmin) role. The default password for admin is "admin". When you log into Manager for the first time, log in as admin. This user is not removable from the user list.
agsadmin: This user is created at the time of installation at OS level as mentioned above. It is also created at the GIS server level. This user is not removable from the user list. The default password is "agsadmin" - the same as the OS level. It is strongly recommended that you change the password immediately after the installation of ArcGIS Server.
agsuser: This user is created at the time of installation at the OS level as mentioned above. It is also created at the GIS server level. This user is not removable from GIS server user list. The default password is "agsuser" - the same as the OS level. It is strongly recommended that you change the password immediately after the installation of ArcGIS Server.
The Install Owner: This user is not created at the GIS server level at the time of installation. For a distributed setup, or if you want to create/update a cache from command line, you must add this user at the GIS server level. The GIS server-level password for this user must match the password at OS level.
Other users: These are the users added by the agsadmin group in Manager after ArcGIS Server has been installed and is running. The virtual users can be added as a member of either 'agsadmin' or 'agsuser' account group.
- The users in the agsadmin group can:
  1. log in to ArcGIS Server Manager to administer ArcGIS Server. Add or modify the server properties.
  2. access & modify the GIS Services settings and configuration, such as: start/stop service, change service configuration such as number of Server instances, resource pool settings etc.
  3. run Server tools on a service such as create/update cache tasks.
- The users in the agsuser group can:
  1. make Internet and LAN connections to ArcGIS Server in ArcCatalog or Web applications to consume GIS Services.

Caution:

It is strongly recommended that you change the password for the admin, agsadmin, and agsuser accounts immediately after the initial setup of ArcGIS Server.

Managing local GIS server users in Manager

In Manager, you can manage these user accounts and assign them to either the User (agsadmin) or Administrator (agsusers) user groups for access to ArcGIS Server.

In ArcGIS Server Manager, navigate to the Local GIS Users page by clicking the GIS Server tab and clicking Local GIS Users in the left-hand panel.

To add a new user account, click Add Users. Here, you can also define the group that the account belongs to.

To remove a user, in the User list page, check the check box next to the user or users you wish to remove and click Delete.

To edit a user account, click the Edit button for the account you wish to edit and change the password, name, and/or user group.

Note:

If you edit the password/group of the user currently logged in to Manager, you must log out of Manager and log back in again.

How to set up local user failover between two SOM machines

In ArcGIS Server on Linux/Solaris, SOC components register with one SOM machine to do its user management. If the user management functionality of the SOM machine is down, the registered SOC machines will not be usable by any other SOM machine. These SOC machines need to point to the other SOM machine for user management to be able to keep working (see the graphic below).

ArcGIS Server on Linux/Solaris provides a script to make an SOC machine automatically point to a secondary SOM machine for user management if the primary SOM machine is down. To do this, enter the following:

cd <ArcGIS Server Installation Directory>/server10.0/servercore/tools/failover
./addIdentityServer.sh

How to automatically sync local ArcGIS Server Users between two SOM machines

If the local GIS Server user failover is set up, the local users in the secondary SOM need to be synced with the primary SOM to make sure the user authentication will work. With ArcGIS Server on Linux/Solaris, local connection users can be automatically synched up between two SOM machines. This feature is very helpful in configuring a multiple-machine deployment.

In the graphic above, SOC machines SOC1, SOC2, SOC3, and SOC4 are registered with SOM1 for authentication. With local user authentication failover set up, if SOM1 is down, these SOC machines will point to SOM2 for local user authentication. SOM2 needs to have the information that these SOCs will need. If the user/passwd/usergroup information in SOM1 and SOM2 are out of sync, these SOC machines might not work properly. ArcGIS Server on Linux/Solaris provides a function to automatically sync the local users' authentication information between SOM1 and SOM2. To do this, enter the following:

cd <ArcGIS Server Installation Directory>/server10.0/servercore/tools/failover/userautosync
./userautosync
usage: ./userautosync <command> [command options]
# There are five commands: add, remove, status, stop, and start.
			      remove - remove the automatic user synchronization SOM machine
			      status - list the SOM machine that is the automatic user synchronization partner
			      stop - stop automatic user synchronization with the partner SOM machine
			      start - start automatic user synchronization with the partner SOM machine
			      add - [The other SOM machine name]

userautosync add:

The add command will set up user autosync between two SOM machines. The users on SOM1 and SOM2 will be combined in both SOMs. If a user exists on both machines, the user information that's been updated/added last will be taken

userautosync add [The other SOM machine name]

For example, on SOM1, running

<ArcGIS Server Installation Directory>/server10.0/servercore/tools/failover/userautosync/userautosync add SOM2

The result will be as follows:

Table 1 - Initial Local User Sync when running "userautosync add" on SOM1
Local Users on SOM1	+	Local Users on SOM2	-->	Local Users on SOM1 and SOM2 after autosync setup
admin		admin		admin (the same as SOM1)
agsadmin		agsadmin		agsadmin (the same as SOM1)
agsuser		agsuser		agsuser (the same as SOM1)
cherry		Cherry		cherry (the same as SOM1)
david		david		david (the same as SOM1)
peter		anthony		peter (from SOM1)
				anthony (from SOM2)

Note:

The user name is case insensitive. So "cherry" in SOM1 and "Cherry" in SOM2 are treated as the same user.

After the initial sync, any changes on SOM1 or SOM2 afterward will be automatically passed on to the other SOM machine. For example, if a new user is added to SOM2, that user information will be added to SOM1 right after the adding action is done on SOM2. If the password or usergroup of a user is changed on SOM1, the changes will take effect on SOM2 right after the change action on SOM1 is done.

userautosync.properties file

Instead of syncing right after any changes on either SOM machine, you can also define a time range for the user autosync to take place through the <ArcGIS Server Installation Directory>/server10.0/servercore/tools/failover/userautosync/userautosync.properties file. You can define the time schedule by giving the starting hour, the finishing hour, and the days of week starting with Sunday. For example:

schedule = 0400-0500 0123

allows synchronization only between 4:00 a.m. and 5:00 a.m. on every Sunday, Monday, Tuesday and Wednesday.

When this property file is modified, it also needs to be modified on the other machine. This property file needs to be the same on both machines.

When userautosync is running with the schedule, for any changes before this synchronization schedule, if there are conflicts between SOM1 and SOM2, the later change will be taken. For example, if the schedule is from 4:00 a.m. to 5:00 a.m. on Monday, the changes that happened before 4:00 a.m. on Monday will be as follows:

Table 2 - Run "userautosync add" on SOM 1 on 3:30am on Monday 6/14/2010 for "schedule = 0400-0500 1" (4:00 a.m.–5:00 a.m. on every Monday)
Local users on SOM1	+	Local users on SOM2	-->	Result - after 4:00 a.m. on Monday 6/14/2010on both SOM1 and SOM2
admin/admin(agsadmin) --> admin/test(agsadmin) on Thursday, 6/10/2010		admin/admin(agsadmin)		admin/admin(agsadmin)
agsadmin/test(agsadmin)		agsadmin/test(agsadmin)		agsadmin/test(agsadmin)
agsuser/test(agsuser)		agsuser/test(agsuser)		agsuser/test(agsuser)
cherry/cherry(agsadmin) --> cherry/cherry(agsuser) at 2:00pm on Saturday, 6/12/10		cherry is deleted at 2:05pm on Saturday, 6/12/10		anthony/anthony(agsadmin)
peter/peter(agsadmin) entered at 3:00pm on Sunday, 6/13/2010		peter/peter(agsadmin)-->peter/peter(agsuser) at 3:05pm on Sunday, 6/13/2010		peter/test(agsadmin)
peter/peter(agsadmin) --> peter/test(agsadmin) at 3:40pm on Sunday, 6/13/2010		anthony/anthony(agsadmin) is entered on Wednesday, 6/9/2010

If you start autosync by running "userautosync add" outside the scheduled time, the initial sync result right at the moment will be different on SOM1 and SOM2. If you run the command on SOM1, initially local user on SOM1 will be pushed to SOM2 but local users on SOM2 will NOT go to SOM1. For exmple, with "schedule = 0400-0500 1", run "userautosync add" on SOM1 at any time outside 4-5am on Monday, 3:30am on 6/14/2010 for instance, the initial sync result will be:

Table 3 - Run "userautosync add" on SOM1 on 3:30am on Monday 6/14/2010 for "schedule = 0400-0500 1" (4:00 a.m.–5:00 a.m. on every Monday)
Local users on SOM1 before running "userautosync add" at 3:30am	Local users on SOM2 before running "userautosync add" at 3:30am	-->	Local users on SOM1 right after running "userautosync add" at 3:30am	Local users on SOM2 right after running "userautosync add" at 3:30am
admin/test(agsadmin)	admin/test(agsadmin)		admin/test(agsadmin)	admin/test(agsadmin)
agsadmin/test(agsadmin)	agsadmin/agsadmin(agsadmin)		agsadmin/test(agsadmin)	agsadmin/test(agsadmin)
agsuser/test(agsuser)	agsuser/test(agsuser)		agsuser/test(agsuser)	agsuser/test(agsuser)
cherry/cherry(agsadmin)	adam/adam(agsuser)		cherry/cherry(agsadmin)	cherry/cherry(agsadmin)
peter/peter(agsuser)	ags/ags(agsadmin)		peter/peter(agsuser)	peter/peter(agsuser)
				adam/adam(agsuser)
				ags/ags(agsadmin)

Then at 4am, userautosync will take effect as Table 2.

If you run "userautosync add" during the scheduled time, the autosync will take effect right away as Table 1. Then autosync will be only happening during the scheduled time. For any changes happened during other times, the effect is as table 2.

If you modified the property file when userautosync is already running, you need to run "userautosync stop" and "userautosync start" for it to take effect. The result by running "userautosync start" will be the same as the rules explained above.

userautosync remove:

This command will remove the automatic user synchronization with the other SOM machine.

userautosync remove

userautosync status:

This command will show the status of the autosync setup. If it's already set up, it will list the other SOM machine and whether the autosynchronization is running or not

userautosync status

userautosync stop:

This command will stop the automatic synchronization if it's already set up and running. The autosync is still configured. If userautosync is only down on one machine, the other machine will keep trying to reach the SOM that's down. The retry pattern is as follows: 10 seconds, 20, 40, 80, until the interval reaches 5 minutes. Then it will continue retrying every 5 minutes. If both machines are stopped, when they are started again, they will try to reach the other machine to autosync users.

userautosync stop

userautosync start:

This command will start the automatic synchronization if it's already set up but not running.

userautosync start

"userautosync start" has the same effect as "userautosync add". For examle, if you "userautosync start" on SOM1, you'll have result as Table 1.

Log file.

There is a log file called user_sync.log under <ArcGIS Server Installation Directory>/server10.0/servercore/tools/failover/userautosync folder. The changes in the local user management will be recorded in this log file.

If ArcGIS Server is down, the userautosync is stopped but still configured. Userautosync will behave the same as running "userautosync stop".

Ports used by Userautosync

The port used by userautosync process is 62001. This is used to send synchronization information between the two SOMs' identity servers. While the "Identity server" uses port 62000 to listen for authentication requests from SOCs.

The "monitor" process uses 2422 as the default port. This is documented in the monitor configuration file at < ArcGIS Server Installation Directory>/server10.0/java/tools/monitor/monitor.xml. This can be modified by the system administrator to any value by un-commenting and updating the following information in the monitor.xml of the local machine.

 <!--<ListenerPort>2422</ListenerPort>-->

If you modify this port number to a non-default value and if this local machine is currently a SOC host for other SOM host(s), then this port number modification must be registered in the MonitorClient properties file < ArcGIS Server Installation Directory>/server10.0/java/tools/monitor/lib/monitor_client.xml on the SOM host(s).

<!-- <MonitorPorts>
	            <Machine name="[MACHINE-NAME]" port="[PORT#]" />										
 </MonitorPorts> -->

Also, if the local host has both SOM and SOC installed then register the port number modifications in the MonitorClient properties on the local host too. This is necessary for the SOM host(s) to successfully run remote operations such as 'diagnostics' on the local machine through the Monitor - this is possible only if the SOM host(s) is aware of the port number on which this Monitor is listening.

To change the default port value from 62001, please follow the steps enlisted below:

Stop server
Edit <ArcGIS Server Installation Directory>/server10.0/servercore/agsidsvr/agsldap/slapd-<hostname>/config/dse.ldif
Change the value of nsslapd-port to the new port number you would like to use.
Edit /etc/remotesa/remotesa.config
Change the value of MWR_LDAPPORT to the new value
Restart server

How to manually sync local GIS server users—Importing and exporting local GIS server users on Linux/Solaris

The local users can also be synced through a tool driven by a shell script called "import_export_users.sh" located at <ArcGIS Server Installation Directory>/server10.0/scripts. This script enables you to export local GIS server users to a text file. These users in a text file can then be imported into any instance of ArcGIS Server for the Linux or Solaris platform using the same tool. This tool is available only for SOM installations. The users listed in this text file can then be imported into any deployment of ArcGIS Server for the Java Platform that has these tools available.

You can also leverage this functionality to maintain a backup of local GIS server users or replicate user information across several instances of the server.

How to import and export Local GIS Server users on Linux/Solaris

You can run the script "<ArcGIS Server Installation Directory>/server10.0/scripts/import_export_users.sh". If you run the script without any input parameters, it will print the tool usage.

# ./import_export_users.sh
NAME 
   import_export_users.sh
SYNOPSIS
   ./import_export_users.sh [OPTION] FILENAME 
DESCRIPTION
   This utility is for exporting ArcGIS Server users to a file importing users into ArcGIS Server.
   -i
      import users from a file specified by FILENAME into ArcGIS Server
   -e
      export ArcGIS Servers users to a file specified by FILENAME
   -f
      overwrite user(s) if exist during import.
      This option can only be used with the import option.
   -w
      import users exported from Windows platform specified by FILENAME
      This option can only be used with the import option.
   -n
      no logging
   -o NEW_LOGFILE_PATH
      path to a directory in which the log file will be written (by default the utility will log results
      in /<ARCGISHOME>/server/user/log/import_export.log)

Exporting Local GIS Server users

ArcGIS Server users can be exported by using the -e option followed by the name of the file that should contain the users. The output of the tool summarizes the export. You can check the log file mentioned for more information on what users were successfully exported and if there were any errors. You can turn off the logging by using the -n option. By default, the logs are located at <ArcGIS Server Installation Directory>/server10.0/server/user/log. However, you can change the directory path by using the -o option.

Example:

[user@machine <ArcGIS Server Installation directory>/server10.0/scripts]# 
./import_export_users.sh -e /tmp/users.dat
EXPORT SUMMARY
-------------------
5 users exported successfully.
Check log file for detailed information at /server/user/log/import_export_Sat_Sep_29_13-24-53_2007.log

[user@machine <ArcGIS Server Installation Directory>/server10.0/scripts]# ./import_export_users.sh -e /tmp/users.dat

Importing Local GIS Server users

Users that were exported by ArcGIS Server on Linux or Solaris can be imported by using the -i option followed by the name of the file that contains the users. The output of the tool summarizes the import. You can check the log file mentioned for more information on what users were successfully imported and if there were any errors. You can turn off the logging by using the -n option. By default, the logs are located at <ArcGIS Server Installation Directory>/server10.0/server/user/log. However, you can change the directory path by using the -o option.

Example:

[user@machine <ArcGIS Server Installation directory>/server10.0scripts]# 
./import_export_users.sh -i /tmp/users.dat
IMPORT SUMMARY
---------------------------
5 users imported successfully.
Check log file for detailed information at /server/user/log/import_export_Sat_Sep_29_13-24-53_2007.log

11/18/2013