ArcGIS Server Java 10.0

= Overview =

ArcGIS Server Java is the codebase that yields two similar versions:


 * ArcGIS Server Java - Windows
 * ArcGIS Server Java - Linux
 * ArcGIS Server Java - Unix

The *nix version of ArcGIS Server Java is fundamentally the same codebase as ArcGIS Server Java with the addition of a number of complex components including LDAP, MainWin, and an Identity Server making very difficult to deploy and support successfully.

= Licensing =

ArcGIS Server Java for Unix follows the Server Licensing model.

= Services Handler =

One of the dynamic properties of ArcGIS Server Java on both Linux & Windows is the ability to export and deploy what is known as the "Services Handler" onto another Java Web Application Server such as Tomcat, which will then expose a REST (http://SERVER/rest) and/or SOAP (http://SERVER/services) endpoint.


 * Is ArcGIS Server Java (9.3.1) supported with a different version of a Services Handler (10.x) supported? No, these two components must be of the same version.

= Configuring Proxy Servers =

UNCONFIRMED / NOTES

FYI: If they deploy the web application created in Server Manager to an external Java Application Server, they will need to set the Java proxy properties(http.proxyHost, http.proxyPort, http.proxyUser, http.proxyPassword) for that the application server.

Java proxy properties documentation: http://download.oracle.com/javase/6/docs/technotes/guides/net/proxies.html

See the last (Proxy Server) section in "ArcGIS Java Manager and Web Server settings":

http://help.arcgis.com/en/arcgisserver/10.0/help/arcgis_server_java_help//index.html#/ArcGIS_Java_Manager_and_Web_Server_settings/009200000096000000/

= Configuring Security =

User Store
The following can be entered into ArcGIS Server Manager > Security > Settings > Security Store > Configure > Active Directory > Configure... (User Store Section):

Hostname:             ssldomain Port:                 389 Base DN:              CN=Users,DC=ssl,DC=local Active Directory URL: ldap://ssldomain:389/CN=Users,DC=ssl,DC=local User-ID Attribute:    CN Administrator's DN:    CN=ssluser,CN=Users,DC=ssl,DC=local Password:             ssluser


 * Note ArcGIS Server will not respect SAMAccountName as the User-ID Attribute value, you must use CN.

Role Store

 * Due to NIM073089, before proceeding further, you must create the following within Active Directory:
 * Create a group called "aaaaa"
 * Add any user to group "aaaaa"

The following can be entered into ArcGIS Server Manager > Security > Settings > Security Store > Configure > Active Directory > Configure... (Role Store Section):

Role Type:                    Role as Entry Base DN:                      CN=Users,DC=ssl,DC=local LDAP URL:                     ldap://ssldomain:389/DC=ssl,DC=local User Attribute in Role Entry: member

External Database

 * When configuring an External Database with AGS 10.0 be sure to use the java 6 version of any JDBC driver used. For example, Oracle would be ojdbc6.jar

Oracle 11g External Database
http://help.arcgis.com/en/arcgisserver/10.0/help/arcgis_server_java_help/index.html#/Configuring_an_external_database_as_the_security_store/0092000013n0000000/

Pre-requisites

 * Oracle 11g Database

Perform the following on the database: CREATE USER username IDENTIFIED BY password DEFAULT TABLESPACE tablespacename TEMPORARY TABLESPACE temp_tablespacename QUOTA UNLIMITED ON tablespacename;

GRANT CONNECT TO username; GRANT RESOURCE TO username;

Steps
1. Copy ojbc6.jar from your Oracle database to ArcGIS Server Java: COPY: \oracle\product\11.2.0\dbhome_1\jdbc\lib\ojdbc6.jar TO: \ArcGIS\Server10.0\java\manager\config\security\lib\ojdbc6.jar 2. Within ArcGIS Server Manager > Security > Settings > Security Store > External Database with your JDBC connection details: JDBC DRIVER: oracle.jdbc.OracleDriver JDBC URL:    jdbc:oracle:thin:@ORACLEHOST:1521:SERVICE_NAME USERNAME:    username PASSWORD:    password

= Supported Platforms =

http://resources.arcgis.com/content/arcgisserver/10.0/arcgis-server-server-requirements

Other platforms known to function:


 * Open Suse 11.x 32-bit
 * Open Suse 11.x 64-bit
 * CentOS 4.x 32-bit
 * CentOS 4.x 64-bit
 * CentOS 5.x 32-bit
 * CentOS 5.x 64-bit

Be advised that ArcGIS Server Java on Linux/Unix can be challenging to install. In addition there are some limitations organizations should consider before pursuing this option: (http://blogs.esri.com/dev/blogs/arcgisjava/archive/2009/11/06/faqs-on-arcgis-java-platform.aspx).

Installation on Linux
Before beginning it is important to understand Linux fundamentals. See Linux for help.

User Permissions
The following file system permissions are required to install & run ArcGIS Server on Linux:


 * "root" user needs rwx (Read Write Execute):
 * /root/
 * /var/tmp/
 * /etc/
 * /
 * /opt/
 * /tmp/
 * "arcgis user" needs r-x (Read Execute):
 * /etc/
 * /opt/
 * /var/tmp/
 * /home/
 * "arcgis user" needs rwx (Read Write Execute):
 * /tmp/
 * /
 * /home/

Example - Valid Permissions
The following example shows valid file system permissions for ArcGIS Server to install and function normally.

[root@6007i957791 ~]# ls -la /home ... drwx-- 4 arcgis arcgis 4096 Aug 23 10:06 arcgis ...

[root@6007i957791 ~]# ls -la /var ... drwxrwxrwt 2 root root 4096 Oct 11  2010 tmp ...

[root@6007i957791 ~]# ls -la / ... drwxr-xr-x  2 arcgis arcgis  4096 Aug 23 10:06 arcgis ... drwxr-xr-x 107 root  root   12288 Aug 23 10:06 etc ... drwxr-xr-x  2 root   root    4096 Oct  1  2009 opt ... drwxr-x--- 18 root   root    4096 Aug 23 10:04 root ... drwxrwxrwt 12 root   root    4096 Aug 23 10:03 tmp ...

File System Flags
All file systems ArcGIS Server touches (see File System Requirements) must support:
 * setuid
 * setguid
 * root access

Example 1 - NOSUID
In the below example, the highlighted "nosuid" flag would break ArcGIS Server since this flag is set on the file system root (/). $ mount /dev/sda1 on / type ext4 (rw,errors=remount-ro, nosuid ) proc on /proc type proc (rw,noexec,nosuid,nodev) dog:/p04 on /p04 type nfs (rw,addr=192.168.0.12) This is because "nosuid" prevents files from getting "setuid" permission. "Setuid" permission allows a file to run as a process owned by the owner of the file, regardless of the user who ran the file. For example, a file (program) called "virus" would want to be owned by root, with setuid set because regardless of who accesses the file, it will run as a root owned process that can basically do anything. For this reason setuid is sometimes surprised (as above) for security purposes.

Example 2 - Remote File Systems
Notice the same file contains a remotely mounted file system at "/p04" which mounts the path "dog:/p04": root@ags# mount /dev/sda1 on / type ext4 (rw,errors=remount-ro) proc on /proc type proc (rw,noexec,nosuid,nodev) /dog:/p04 on /p04 type nfs (rw,addr=192.168.0.12) If ArcGIS Server install path followed used this file system (/p04/) then it would be necessary to confirm that the NFS server supports remote access as "root" and the "arcgis user". It is very common for NFS servers to disallow this as it presents a significant security risk. For this reason Esri does not recommend using a remote file system for any aspect of the ArcGIS Server system.

Inspect the Remote File System NFS Server Configuration

Continuing with Example 2, we find that we're trying to deploy ArcGIS Server on a remote file system hosted on an NFS server (/dog:/p04). We must then inspect that server to verify the NFS server is configured as follows: root@p04# /etc/exports /p04	*(rw, /no_root_squash ) As above the "no_root_squash" flag must be set otherwise ArcGIS Server will fail to install or function with a remote file system.

User Account Requirements
ArcGIS Server installation requires three (3) accounts:


 * User/Pass: agsadmin/agsadmin
 * The user agsadmin is used to perform authentication between the Web & GIS tiers. This user is found within the  server.properties file within the REST endpoint within Tomcat.  This user account is also referenced by the Java ArcGIS Server Manager > GIS Server > Local GIS Users interface.
 * The above user can be found within the /etc/passwd file on Linux installations.


 * User/Pass: agsuser/agsuser
 * The above user is defined by the person installing ArcGIS Server. It is used to run the ArcGIS Server related processes. This user account is also referenced by the Java ArcGIS Server Manager > GIS Server > Local GIS Users interface.
 * The above user can be found within the /etc/passwd file on Linux installations.


 * User/Pass:  / 
 * The above user is defined by the person installing ArcGIS Server. It is used to run the ArcGIS Server related processes.
 * The above user can be found within the /etc/passwd file on Linux installations.

Verify/Install Required Packages
[root@6007linux ~]# rpm -qa --queryformat "%{NAME} %{ARCH} \n" | sort > /tmp/packages.out

The /tmp/packages.out must contain all of the packages outlined below:

Note 32-bit packages will look like "i386", "i486", "i586", "i686", etc. 64-bit packages will look like "x86_64". Any Architecture packages will appear as "noarch".

SELinux
that are prohibited by the default deployment of SELinux, the installer itself will not complete with SELinux enabled. [root@6007linux ~]# setenforce 0
 * Disable SELinux.
 * MainWin specifically invokes library actions

Advanced SELinux
For more detailed information, click Advanced SELinux

Pre-Create Users, Groups, and Directories
The following steps, while optional, have been found to improve the likelyhood of a successful deployment (largely because they accomplish several error-prone tasks manually that are not well handled by the installer.)

[root@6007linux ~]# useradd agsuser [root@6007linux ~]# mkdir /arcgis [root@6007linux ~]# chown -R agsuser:agsuser /arcgis [root@6007linux ~]# chmod 755 /arcgis/ [root@6007linux ~]# /Setup

This last command will launch the install.

Manual Removal
[root@6007linux ~]# /scripts/stopserver
 * Shutdown ArcGIS Server
 * Kill any ArcGIS Server processes that are still running:
 * arcsom
 * arcsoc
 * ns-slapd
 * java
 * remotesa

[root@6007linux ~]# ps -ef f ww | grep [root@6007linux ~]# kill -9    (Kill any Process ID that shows up in the list)

[root@6007linux ~]# /scripts/uninstallArcGISServer
 * Run the uninstallArcGISServer script (from arcgis/scripts) (this may fail that is ok)

[root@6007linux ~]#cp –Rv  /arcgisserver_backup
 * Backup ArcGIS Server Files before Removal

[root@6007linux ~]# rm -rf /root/*arcgis* [root@6007linux ~]# rm -rf /var/tmp/* [root@6007linux ~]# rm -rf /etc/mainwin.conf [root@6007linux ~]# rm -rf /etc/remotesa [root@6007linux ~]# rm -rf /etc/init.d/mwcore_services [root@6007linux ~]# rm -rf  [root@6007linux ~]# rm -rf /opt/mainsoft
 * Remove ArcGIS Server

= Troubleshooting =

Server_diag_tool
The "Server_diag_tool" is the most powerful troubleshooting tool Esri Support has with respect to ArcGIS Server on Linux/Unix environments. This script, developed by development, for support, tests more than 40 areas of the software and verifies they are functioning normally. The output will return FAIL/PASS for each area:

[root@6007linux ~]# /scripts/server_diag_tool

To interpret the results from this tool see: Interpreting Server Diagnostics

ServerConfig Script
This is the equivalent of the "GIS Server Post-Install".

[root@6007linux ~]# /scripts/ServerConfig

The response from this command, often helps to troubleshoot the problem as it follows the various steps involved in configuring ArcGIS Server, while in other cases, executing this command "resets" the ArcGIS Server installation and fixes the deployment.

Debugging ServerConfig Script
Edit the ServerConfig script:

[root@6007linux ~]# vi /scripts/ServerConfig

Enter the highlighted text below and save the script:

#!/bin/sh

set -x

#This script expects the files - .pi.xml, .arcgisid.dat - to reside in the .Server directory ...

Now run the ServerConfig script. The output will be very verbose but can be used to figure out what is failing.

Logging
[root@6007linux ~]# /scripts/switchlogging on
 * Verbose Logging

[root@6007linux tmp]# tar -cvhf /tmp/logs.tar /logs
 * Capturing All Logs

The above command will provide tar of verbose logs generated by ArcGIS Server.

Reset Windows Registry Emulation
ArcGIS Server emulates Windows RPC and Registry functionality in order to allow DCOM client-server and server-server communication to take place. As such, AGS libraries are registered and DCOM functionality is configured within a program called MainWin which emulates this functionality.

It may be beneficial to reset the MainWin DCOM functionality by re-creating the registry and its settings. This can be accomplished through the following steps (version 10.0 specific; other versions may have different paths):

[root@6007linux tmp]# <AGS Install Path>/scripts/stopserver
 * Stop ArcGIS Server

[root@6007linux tmp]# mv hklm_linux.bin hklm_linux.bin.orig
 * Remove or rename the registry file
 * Located at <AGS Install Path>/servercore/mwcore/mwcoredata/ /.mw/hklm_linux.bin

[root@6007linux tmp]# <AGS Install Path>/scripts/startserver
 * Start ArcGIS Server

[root@6007linux tmp]# <AGS Install Path>/scripts/ServerConfig
 * Run ServerConfig Script to rebuild registry
 * This will rebuild the registry
 * Running copy size will update and should roughly/exactly match the original size


 * At this point, ArcGIS Server should be up and running, with a newly created registry with default settings

Check for missing Linux libraries
ArcGIS Server requires several pre-requisite Linux libraries in order to support certain functions of map publishing and data communication. The list of pre-requisite libraries is available online in the system requirements page.

Occasionally it is necessary to determine whether libraries are missing in order to troubleshoot problems in functionality. Typical symptoms include the inability to complete the ServerConfig script or publish certain types of GIS services. The proper installation of pre-requisite libraries can be verified through the following commands:


 * Log in as 'root'

[root@6007linux tmp]# source <AGS Install Path>/servercore/.Server/init_server.sh
 * Source the init_server.sh script
 * This will configure the login shell with the correct ArcGIS Server binary and library paths

[root@6007linux tmp]# ldd <AGS Install Path>/bin/*.so | grep -i "not found"
 * Run the Linux dynamic library tool to look for missing libraries


 * You will almost always see several results. Some of these are "normal" in that they are only installed when a specific database client is installed. Some ArcGIS Server functionality requires the presence of external database client libraries to properly function.


 * If your installation is not configured to access data on ArcSDE databases, you can safely ignore the following missing libraries:
 * Informix Client
 * libthcli libifgls libifglx libifdmr
 * db2 Client
 * libdb2
 * Oracle Client
 * libwtc9 libclntsh
 * ECW Jpeg2000 GDAL
 * libecwj2
 * Perl (ArcGIS Server specific binaries only)
 * libdb
 * identityadmin (ArcGIS Server specific binary)
 * libsasl
 * OpenMotif
 * libXm
 * ???? (Something ArcGIS Server specific, ArcInfo Workstation?)
 * libaiarcapi.so


 * Any other libraries that you see should be considered as likely missing on the system and need to be added to allow functionality of ArcGIS Server.

Run the Linux Post Install by hand
Similar to the Windows version, the Linux version of ArcGIS Server has a "Post Install" process that configures many of the critical settings of ArcGIS Server. This process runs as part of the ./server10.0/scripts/ServerConfig script. Occasionally it may be helpful to run this process by hand, usually when it's failing to complete, to see if any additional information can be obtained.

To run ./server10.0/bin/serverpostinstall.exe by hand, complete the following steps (these steps can be taken from the ServerConfig script itself): [root@6007linux tmp]# source <AGS Install Path>/servercore/.Server/init_server.sh [root@6007linux tmp]# PATH=<AGS Install Path>/servercore/agsidsvr/bin:${PATH}; export PATH [root@6007linux tmp]# ESRI_AGS_PICFG=<AGS Install Path>/servercore/.Server/.serverpi.xml; export ESRI_AGS_PICFG [root@6007linux tmp]# <AGS Install Path>/bin/serverpostinstall.exe /silent
 * Source the ArcGIS Server environmental configuration script
 * Add the identity server bin folder to the path
 * Declare the environment variable pointing to the post install silent configuration file
 * Run the post install binary

In theory, it's possible to run serverpostinstall.exe without the /silent switch, but I haven't been able to determine what all the correct parameters are. This process may or may not provide any useful output, but it's sometimes helpful.

Disaster Recovery
Pursue the below steps only in cases where all other troubleshooting has failed and you have a production server down that demands an immediate response:

1. Stop/Kill all ArcGIS Server processes. root@server# /arcgis/server/scripts/stopserver root@server# ps -ef | grep arcgis root@server# kill -9 <PID> <PID> <PID>

2. Copy the "server" folder out of the ArcGIS directory.

3. Copy the "keycodes" file out of the ArcGIS\sysgen directory. root@server# cp -r /arcgis/server /tmp/server.backup root@server# cp -r /arcgis/sysgen /tmp/sysgen.backup

4. Delete the ArcGIS Server install folder. root@server# rm -rf /arcgis

5. Delete the hidden MainWin product registry file. root@server# rm -rf /var/tmp/productregistry

6. Re-install ArcGIS Server. root@server# /mnt/iso/Setup

7. Stop ArcGIS Server. root@server# /arcgis/scripts/stopserver

8. Restore the "keycodes" file to the ArcGIS\sysgen directory

9. Restore the "server" folder to the ArcGIS directory. arcgis@server$ cp -r /tmp/server.backup /arcgis/server arcgis@server$ cp -r /tmp/sysgen /arcgis

10. Start ArcGIS Server. arcgis@server$ /arcgis/scripts/startserver

= ArcGIS Server 10.1 =

ArcGIS Server 10.1 also known as the "Discovery" Project is a complete re-architecture of the ArcGIS Server Platform. Discovery is a completely Java based, self contained solution, with no reliance on .NET, DCOM, MainWin, LDAP. For this reason it is not only faster and more reliable, but provides a single code base to support both Windows and Linux deployments natively.

ArcGIS Server 10.1 is available in the following versions:


 * ArcGIS Server Windows 10.1
 * ArcGIS Server Linux 10.1

Per Tech Transfer June 2011, ArcGIS Server 10.1 will not support cross-platform installations, i.e. 1 Linux SOC, 1 Windows SOC.

= ArcGIS Server Clients (Version Independent) =

Anything that can consume and utilize an ArcGIS Server service is considered an ArcGIS Server client. These include:


 * ArcGIS Desktop
 * ArcGIS Server
 * ESRI Sharepoint Web Part