IBM i Access - ACS Getting Started

5733XJ1 IBM i Access Client Solutions - GettingStarted

The content of this document was last updated on: March 19, 2024
 

0.5 QuickStartGuide

The QuickStartGuide contains instructions for deploying the product that work for most users running Windows, Mac, or Linux. To install this product for a single user, or for a multi-user PC, see the QuickStartGuide in the Documentation folder.

Additional details about the product, other deployment options and customizing the product are included in the remainder of this document.

Contents:

1.0 Introduction

IBM i Access Client Solutions is the newest member of the IBM i Access family of products. It provides a Java based platform-independent interface which runs on most operating systems that support Java including Linux, Mac, Windows, and IBM i. IBM i Access Client Solutions consolidates the most commonly used tasks for managing your IBM i into one simplified location.

IBM i Access Client Solutions uses the same IBM i host servers as the other IBM i Access Family products.

Also available are four optional packages which include middleware for using and developing client applications for Windows, Linux, Mac, and PASE:
    IBM i Access Client Solutions - Windows Application Package
    IBM i Access Client Solutions - Linux Application Package
    IBM i Access Client Solutions - Mac Application Package
    IBM i Access Client Solutions - PASE Application Package

Customers using IBM i 7.3 or later that have current entitlement can acquire IBM i Access Client Solutions by either of the following two methods:

• Download IBM i Access Client Solutions package.
• Non-English and 32bit versions of the Windows application package can be downloaded from the Entitled Systems Support (ESS) website under 5761-SS1 or 5770-SS1.

Customers can acquire media by ordering 5761-SS1 or 5770-SS1 refresh feature 6288. The physical media contains a runnable version of the product which allows you to run the product directly from the CD. The physical media also includes a .zip file of the product which can be copied and extracted to a location of your choice. The physical media for IBM i Access Client Solutions does not contain the optional Windows, Linux, Mac, and PASE Application Packages.

For additional information visit:
    IBM i Access Client Solutions

For the latest information about IBM i Access Family products visit:
    IBM i Access Family

2.0 Features

Features of IBM i Access Client Solutions include:

• a full featured 5250 display emulator based on IBM Rational Host-on-Demand. In addition to all the 5250 display features you are accustomed to when using IBM i Access for Windows, some additional features are:
  • tab support which allows multiple sessions to share a single viewing area
  • mouse wheel support allowing intuitive scrolling between pages
  • switching between languages can be done without rebooting your workstation
  • concurrent display sessions with different host code pages allowing separate languages within different emulator sessions
• Printer emulation
• a 5250 Session Manager modeled after IBM Personal Communications Session Manager which can be used for managing all of your 5250 emulator sessions
• Data Transfer which provides the ability to transfer data from/to your IBM i database to/from various file types on your workstation such as OpenDocument spreadsheet (*.ods), Excel Workbook (*.xlsx) and other file formats
• Printer Output provides an interface that allows you to view files in the IBM i output queues and also provides the capability to download these files to your client system.
• Integrated File System provides an interface for browsing the Integrated File System of your IBM i. Supported actions include view, download/upload to/from your PC and send to other IBM i partitions.
• a Virtual Control Panel with a graphical interface to the IBM i operation panel
• 5250 emulation for LAN, HMC and FSM consoles
• consolidation for system management interfaces including Advanced System Management Interface (ASMI), Copy Services Manager for i, Db2 Mirror for i, Digital Certificate Manager, DS HMC, Hardware Management Console (HMC), Integrated Virtualization Manager, Spectrum Control, Tape Management, Web (HTTP) Administration for i
• launch capability to IBM Navigator for i using your default browser
• Database features like Run SQL Scripts and SQL Performance Center.

The optional Windows Application Package includes:

• connectivity to Db2 for i using ODBC, .Net and OLE DB
• Programming Toolkit for accessing IBM i system objects
• support for TLS/SSL connections

The optional Linux, Mac, and PASE Application Package includes:

• an ODBC driver for accessing Db2 for i and supports full 64-bit ODBC data types.
• support for TLS/SSL connections

3.0 Prerequisites

3.1 Prerequisites (workstation)

IBM i Access Client Solutions runs on most operating systems that support Java 8.0 or higher including various versions of Linux, Mac and Windows.
Note: ACS may not be able to locate Java 8 on macOS 11.0 Big Sur. We recommend installing Java 11 from https://aws.amazon.com/corretto/ since that version contains the most recent updates for keystroke issues.

Recommendation:
Keeping your version of Java at the most current version makes sure you have all the latest fixes and security patches.

One way to check the version of Java installed on your system is to bring up a prompt where a command may be entered (Command Prompt, Shell, Terminal, etc) and then type the command:
    java -version

The following output indicates version 8.0 is installed:
    java version "1.8.0_191"
The 191 in this example refers to the update level.

Here are some websites of Java providers. Make sure you are running with the most up-to-date version of Java for your platform.
    https://developer.ibm.com/languages/java/semeru-runtimes/downloads/
    https://aws.amazon.com/corretto/   
    https://adoptopenjdk.net/
    http://openjdk.java.net/install
    http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
    http://www.oracle.com/technetwork/java/javase/downloads/index.html

Technote for Mac:
When installing Java on Mac, select a JDK instead of a JRE. The JRE for Mac installs Java for only the browser. It does not install Java for other applications. Installing the JDK makes Java available to other applications such as IBM i Access Client Solutions.

3.2 Prerequisites (Connectivity to IBM i)

IBM i Access Client Solutions connects to any supported IBM i release.

IBM i Access Client Solutions uses the same IBM i host servers as the other IBM i Access Family products.

If you use Navigator for i, load and apply the latest "IBM HTTP Server for i" Group PTF for your release. See the following web page for the latest IBM i Group PTFs: https://www.ibm.com/support/pages/ibm-i-group-ptfs-level.

4.0 Product Contents

The following files and directories are contained in the product .zip file:

acsbundle.jar       - an executable jar file of the product
AcsConfig.properties- file containing configuration settings (also exists
                      inside acsbundle.jar)

Mac_Application     - directory containing install script for Mac

Linux_Application   - directory containing install scripts for Linux

Windows_Application - directory containing install scripts for Windows

Start_Programs      - directory containing platform specific binary files which
                      can be used to start the product.
    Linux_i386-32
    Linux_x86-64
    Mac_i386-32_x86-64
    Windows_i386-32
    Windows_x86-64

Documentation       - directory containing documentation
  QuickStartGuide   - information for how to get started
  GettingStarted    - detailed information about the product
  License           - directory containing terms and conditions for usage
  Notices           - directory containing notices and information
  properties        - directory containing product version information
  Sample_Scripts    - directory containing sample scripts which can be used to
                      start the product if the binary files in Start_Programs
                      do not work.
    Linux_Mac_Other - directory of Perl scripts for starting the product
                      on any platform where Perl is available.
    Windows         - directory containing a JScript for starting on Windows

Icons               - directory containing files which can be used as icons

Fonts               - directory where additional monospaced fonts may be 
                      added for 5250 emulation

5.0 Installation

The packaging of IBM i Access Client Solutions provides several installation options from the very simple single user installation, to the more advanced multi-user installations.

Installation scripts have been provided in the Mac_Application, Linux_Application, and Windows_Application folders (see section 4.0 Product Contents) which can be used for a variety of installation options.

For a single user installation on Mac, Linux, and Windows, or a multi-user installation on a Windows PC, see the QuickStartGuide. The QuickStartGuide explains how to use the provided installation scripts for doing these types of simple installs.

If you are an administrator planning on deploying this to several users, you should read the following articles:
IBM i Access Client Solutions: Customization and deployment made easy
IBM i Access Client Solutions: Customization and deployment questions answered
These articles explain how an administrator can pre-customize the installation for multiple users before deployment by using the /AdminConfig option supported by the installation scripts.

For administrators that would like to automate the install in silent mode, use the /AdminConfig parameter to pre-configure the installation. Then use the /Q parameter during the actual installation. For Example:

    Windows_Application\install_acs_64.js /AdminConfig
    Windows_Application\install_acs_64.js /Q

In addition to the above options, you also have the option of just unpacking the .zip file to any location of your choice. This can be any location where the workstation has read authority to access the files. This includes the local hard disk drive, a remote network (shared) drive or portable media such as a CD or USB flash drive. Unpacking the .zip file completes the installation.

Technical Note:
Some archive utilities do not preserve all the saved file attributes. For example, on Mac and Linux platforms, the unzip command is usually a better choice than the jar command. For additional information, see section 6.0 File Permissions.

5.1 Updating an Existing Installation

Enhancements and fixes are available on a periodic basis. These updates are provided as a complete product installation. When these updates are available, you should update your existing installation.

For users maintaining their own installation:

Option 1:
To update an existing installation that was installed by using the installation scripts, extract the contents of a newer version of the product. Invoke the installation script from this new version in the same manner as was done during the initial installation. This updates the product files without changing the existing configuration.

Option 2:
If you chose to install the product without using the installation scripts by extracting the contents of the .zip file to some location of your choice, then to update the product, you need to extract the contents of the newer version of the product over the top of the existing version. Keep in mind, you should save and restore the contents of AcsConfig.properties if you made custom changes to it.

For administrators maintaining a version of the product in a central location accessed by multiple users:
Extract the contents of the newer version over the top of the existing version. If you have made custom changes to the AcsConfig.properties file, you should save AcsConfig.properties before extracting the contents of the new version of the product over an existing version. After you have extracted the contents of the new version of the product and have restored AcsConfig.properties, your users need to take one of the following options:

Option 1:
If the users are running directly from the remote location, no further action is needed. Have them restart the product to pick up the new updates.

Option 2:
Run the install script in the same manner as the initial installation to update the local installation.

Option 3:
If you have set up an IBM i Update Location, section 5.2, have your users select Help->Check for Updates from the main GUI. A panel should appear telling them an update is available. Have them select Install Update. This option may also be run from the command line using the INSTALLUPDATES plug-in.

After following the appropriate steps above, restart the product. Help->About from the main GUI can be used to verify the updates were applied.

5.2 Setting up an IBM i Update Location

Administrators can use an IBM i system as their central location for doing installs and applying updates. Regardless of how you initially deploy the product to your users, you can use a central location on an IBM i so that your users can apply an update with a click of a button. Here are the steps:

• Decide what IBM i system to use as the central location.
• Extract the latest product .zip file (IBMiAccess_v1r1.zip) to any place in the IBM i Integrated File System (IFS).
• Set the following properties in the AcsConfig.properties file:

       com.ibm.iaccess.CheckUpdateSystem=system_name                          (see Note 1 below)
       com.ibm.iaccess.CheckUpdatePath=/path_where_zip_was_extracted          (see Note 2 below)
  

Setting the com.ibm.iaccess.CheckUpdateSystem property causes Help->Check for Updates to behave differently. Instead of checking an external web location for the availability of an updated version, the above IBM i location is checked for updated product files. An update is detected when the timestamp of any required product file changes. The timestamp is displayed on the Help->Check for Updates panel with an option to install the update.

The user will need valid credentials to the system specified for com.ibm.iaccess.CheckUpdateSystem. If their credentials have not already been cached from a previous connection to this system, they are prompted to provide valid credentials. Failing to provide valid credentials will result in updates not being detected.

Users that have an IBM i Update Location configured and have selected the option "Notify when update is available" under Edit->Preferences, will not be prompted to provide credentials. They will only get notified of an available update if they have successfully connected to the com.ibm.iaccess.CheckUpdateSystem since the last time they logged in to their PC.

Note:

1. This feature is only enabled when using version 1.1.8.3 or higher.
   Beginning with version 1.1.8.6, this feature can also be enabled from the main GUI at Edit->Preferences. See System for checking updates on the General tab. If the system is set by the property in AcsConfig.properties, it is displayed on this panel and the option to select a different system is disabled.  If System for checking updates is set to Select a system, then Help->Check for Updates will check an IBM web location for the availability of the next update.
2. If com.ibm.iaccess.CheckUpdatePath is not set, the default location is assumed to be:
           /QIBM/ProdData/Access/ACS/Base
   Note: IBM now has release-specific PTFs that extract the contents of the product .zip file (IBMiAccess_v1r1.zip) to this location (see section 5.3). Administrators may extract IBMiAccess_v1r1.zip to this location themselves as long as they are aware that if the PTF is applied, this location is updated.
3. The AcsConfig.properties file along side acsbundle.jar gets propagated to the local PC during the initial deployment, but does not get updated during a product update. To leverage this feature, you will need to update AcsConfig.properties on the user's PC before selecting Help->Check for Updates.
4. Beginning with version 1.1.9.1, if a JRE (Java Runtime Environment) has been placed in the same directory as acslaunch_win-64.exe OR acslaunch_win-32.exe, this feature will detect when the JRE has been updated and will present an option to update it.
    

Special note for administrators that maintain a customized AcsConfig.properties file within acsbundle.jar:
This feature downloads the acsbundle.jar that exists on the IBM i at the specified location. No special processing is done to maintain a customized version of the AcsConfig.properties file during an update. If you have previously customized the AcsConfig.properties file inside acsbundle.jar, you will need to make sure the new version of acsbundle.jar contains your desired customizations before making it available for download.

5.3 Optional IBM i PTFs

For Administrators that want to maintain a centralized location on an IBM i for their users to install and update the product, release-specific PTFs are available that will provide the extracted contents of IBMiAccess_v1r1.zip at:
        /QIBM/ProdData/Access/ACS/Base

See the following web page for the latest PTFs: https://www.ibm.com/support/pages/ibm-i-access-client-solutions-5733xj1. These PTFs are superseded for each product update and will normally be available within 2 weeks of the availability of the product update.

6.0 File Permissions

Section 7.0 Starting the Product describes several different ways to start IBM i Access Client Solutions. If you use one of the provided binary files or scripts to start the product, you need to make sure its file permissions have the execute permission enabled. The file permissions assigned while unpacking the .zip file are determined by several factors including the operating system, the archive utility used to unpack the .zip file, the authority of the user, etc.

If you have trouble using one of the provided binary files or scripts, check the file permissions. The following sections describe some methods for checking the file permissions.

6.1 File Permissions (Linux, Mac, AIX)

For unix-like operating systems, you can use the following command from a shell or terminal prompt to check the permissions of a file:

    ls -l <file>             

To change the permissions of a file, you can use the following command:

    chmod <permission> <file>  

    chmod a+rx <file>

    chmod 755 <file>

Additional help for the ls and chmod commands is readily available on the internet.

6.2 File Permissions (Windows)

For Windows, while viewing the file using Windows explorer, right-click the file and select properties. The security tab should contain the file permissions. Make sure you have Read and Execute permission.

On recent versions of Windows, you may also use the icacls command to view and change the permission of a file.

7.0 Starting the Product

There are multiple ways to start IBM i Access Client Solutions. If you used the installation scripts to install the product, the easiest way to start the product is found in the QuickStartGuide.

If the product was not installed using the installation scripts, the remainder of this section will describe alternative ways to start the product. Since there are a variety of ways and locations how/where Java can be installed, some of the methods may require additional configuration. If one of the methods below does not work, try a different method. In some cases, additional guidance is provided.

When using a binary file or script as described below, the binary file or script must be in the same directory structure as contained in the .zip file. For convenience, you may also copy/move the binary file(s) and/or scripts for your platform(s) to the same directory where the acsbundle.jar exists.

7.1 Starting the Product

To start the product from a file viewer (e.g. Windows Explorer, Mac OS X Finder, etc) using a platform specific binary file, locate the sub-directory in Start_Programs that identifies your operating system and hardware architecture.

Locate the binary file your operating system recognizes. Then double-click it to start the product. You may also start the product with this binary file from a Command Prompt, Terminal, or Shell.

If you get the following error:
    "Error loading Java module."
IBM i Access Client solutions could not find a Java installation in a location it recognizes. You may try one of the following methods in sections:
    7.1.1 Starting the Product - Additional Options
    7.2 Starting the Product (using a script)
    7.3 Starting the Product (using the command-line)

7.1.1 Starting the Product - Additional Options

You may also try one of the following methods when trying to use the binary file for your platform. These methods allow you to identify which Java Runtime Environment (JRE) should be used to start the product. See section 7.1.2 Finding the Java Home Path for how to locate the Java home path on your workstation. These additional methods are only supported on Linux and Windows platforms:

• Set the JAVA_HOME environment variable to the Java home path (OR)
• Use the -vm option on the binary command to specify the Java home path. Specify -h on the binary command for additional help (OR)
• Copy a Java Runtime Environment (JRE) directory structure to the same directory as the binary file you are trying use.

7.1.2 Finding the Java Home Path

If you can start the product using one of the methods in section:
    7.2 Starting the Product (using a script) (OR)
    7.3 Starting the Product (using the command-line)
then you can determine the Java home path on your workstation from the IBM i Access Client Solutions main GUI. On the menu bar, select
    Help->About
    The java.home path is displayed on this panel.

The java.home property contains the location of the Java home path for your workstation. This is the path you will need to specify when setting the JAVA_HOME environment variable or when using the -vm option on the command.

7.1.2.1 Finding the Java Home Path (on Windows)

On Windows platforms, search for java.exe. The Java binary is normally located in either a bin or jre/bin sub-directory below the Java home path. The Java home path may be used when setting either the JAVA_HOME environment variable or when using the -vm option on the command.

7.1.2.2 Finding the Java Home Path (on Linux)

On Linux you can use the "which" command:

    which java

Resolve any symbolic links until you finally get to the actual binary file for the java command. You can resolve symbolic links by using the ls command with the -l option:

    ls -l <file>

7.2 Starting the Product (using a script)

There is a Sample_Scripts directory in the Documentation directory.

The preferred way to start the product is by using a platform specific binary file available in Start_Programs. The scripts in Sample_Scripts should only be used if the platform specific binary does not work.

To start the product from a file system browser (e.g. Windows Explorer, Mac OS X Finder, etc) using one of the supplied scripts, locate the script in the Sample_Scripts sub-directory that is compatible with your operating system.

Most non-Windows based operating systems have Perl available by default. The Sample_Scripts/Linux_Mac_Other directory contains a Perl script (with three different file extensions) which can be used to start the product on any platform where Perl is available. Select the file that has a file extension that your operating system will recognize as a Perl script.

Windows based operating systems have JScript available by default. The Sample_Script/Windows directory contains a JScript that can be used to start the product on Windows operating systems.

Using a platform specific method to browse your file system (e.g. Windows Explorer, Mac OS X Finder, etc), locate the script your operating system recognizes. Then, double-click it to start the product. You may also start the product with this script from a Command Prompt, Terminal, or Shell.

7.3 Starting the Product (using the command-line)

You may also start the product from the command-line from any place you can enter a command (Command Prompt, Terminal, Shell, etc)

    java -Xmx1024m -jar <path>/acsbundle.jar

    java -Xmx1024m -jar V:/some_location/acsbundle.jar

    <java_path>java -jar V:/some_location/acsbundle.jar

See section 7.1.2 Finding the Java Home Path for determining the complete path to the java command.

You may also use any of the programs or scripts from the command-line. For example:

    /Product/Location/Start_Programs/Linux_x86-64/acslaunch_linux-64
    /Product/Location/Start_Programs/Mac_i386-32_x86-64/acslaunch_mac
    C:\Product\Location\Start_Programs\Windows_x86-64\acslaunch_win-64.exe

Technical Note:
On most platforms, the Java Virtual machine heap space defaults to a maximum size that is too small to use multiple functions within the IBM i Access Client Solutions product. A one gigabyte maximum heap size (-Xmx1024m) is the recommended minimum size. Specifying sizes smaller than one gigabyte or using the default heap size may produce an OutOfMemoryException.

8.0 Configuration

Add a system configuration for each IBM i system you want to use or manage. To add a system configuration, select System Configurations from the Management tasks. Then select New. On the General tab, enter the System name. To get started, the System name is all that is necessary for performing General tasks.

When you have finished, select OK to save the information you entered for this system, or select Save/New if you have additional systems you would like to add to the configuration.

To configure a system to make a TLS/SSL connection, see Configuring Secure Connections.

You may add new systems to your configuration or update existing configurations using the General, Connection, or the Console tabs at any time.

For Console tasks, additional configuration is required. Console configurations are automatically associated with the System name you entered on the General tab. To enter the console configuration for a system, select System Configurations from the Management tasks. Select New or Edit. Then select the Console tab. The 5250 Console task requires a configured LAN console or a configured HMC console. If you do not have a configured LAN or HMC console, see section 9.9 Establishing a Console Connection to IBM i.

The Hardware Management Interface task requires a configured hardware management interface. You may enter up to six hardware management interface configurations.
Note: "Hardware Management Interface 1" and "Hardware Management Interface 2" may be renamed by setting properties com.ibm.iaccess.HMI1 and com.ibm.iaccess.HMI2 in AcsConfig.properties. 

When you have finished, select Close on the System Configurations panel.

Using the System drop-down box on the main IBM i Access Client Solutions panel, select a System. All Console tasks automatically associate the selected System (entered on the General tab) with the console configuration (entered on the Console tab).

You may now select a task for the selected system. If you select a Console task which does not have the corresponding information entered on the Console configuration tab, an error message is displayed.

8.1 Configuration Location

By default, each user will have their own unique location for their configuration. The configuration root directory is determined in a platform dependent manner. The configuration directories are created during the initial start-up. To see where the configuration directory is:
    Start the product (see section 7.0 Starting the Product)
    Edit->Preferences
    Select the Local Settings tab
    Configuration Root

The configuration location cannot be changed while the product is running. To change the location of the configuration, see section 9.3 Changing Configuration Location

9.0 Advanced Topics

9.1 More command-line Options

Many of the functions that are available from the main GUI are also available from the command-line. These functions may be invoked by providing the appropriate parameters to any of the command-line options shown in:
section 7.3 Starting the Product (using the command-line)

For example:

    Start_Programs\Windows_x86-64\acslaunch_win-64.exe parm1 parm2 ...

Only the additional parameters are shown in the following sections:

9.1.1 Backup

/PLUGIN=backup  [/file=<filename>]
    <filename> is the name of the file to be created

This will save the current configuration to the specified file. The resulting file may be used as input to the Restore command-line option on the same or different workstation (regardless of operating system).

The location of the configuration to be saved is determined by the property:

    com.ibm.iaccess.AcsBaseDirectory

This function is equivalent to File->Export Configuration from the main GUI.

9.1.2 Restore

/PLUGIN=restore /file=<filename>
    <filename> is the location of the file created by Backup

The location of the restored configuration is determined by the property:

    com.ibm.iaccess.AcsBaseDirectory

This function is equivalent to File->Import Configuration from the main GUI.

Note:
To avoid importing the default user name specified on the Connection tab of a System Configuration, place the following property in the AcsConfig.properties file.

    com.ibm.iaccess.ResetDefaultUserOnImport=true

9.1.3 Certdl

/PLUGIN=certdl  /SYSTEM=<system>

9.1.4 Cfg

/PLUGIN=cfg     /GUI

    /GUI        - this option will start the System Configurations GUI
                  This is equivalent to launching System Configurations from the main GUI.
                  Note: Setting com.ibm.iaccess.CfgActionsRestricted=true in AcsConfig.properties
                  will hide the New/Edit/Copy/Delete buttons on the System Configurations panel.

/PLUGIN=cfg     /LIST

    /LIST       - list configured systems with their connection options


/PLUGIN=cfg     /AddSystemGroup /SystemGroupName=<name>;

    /AddSystemGroup  - create a new system group (if it does not already exist)
    /SystemGroupName - name of the system group to be created


/PLUGIN=cfg     /system=<system>
                                 [/description=<description>]
                                 [/SystemGroupName=<group name>]
                                 [/ipaddr=<frequency>] [/userid=<userid>]
                                 [/ssl=<switch>]
                                 [/5250path=<path>]
                                 [/HMI1=<path>] ... [/WebHTTPAdmin=<path>]
                                 [/del]  [/r]

    /system     - name of the system
    /description- help text describing the system
    /SystemGroupName - name of system group. If not provided, the system will go in the default group.
    /ipaddr     - when a connection is requested, this value determines whether
                  or not a lookup of the IP address will occur. Valid frequencies
                  are:
                      ALWAYS - lookup IP address for each connection
                      HOURLY, DAILY, WEEKLY - lookup IP address if the amount of
                          time has elapsed since the last lookup
                      IP address - if an IP address is specified, the lookup
                          frequency is assumed to be NEVER
    /userid     - user id for a user
                  may also be set to the following values:
                      *SHARE        - prompts once for logon credentials that
                                      will be shared by systems using this option
                      *PROMPTALWAYS - prompts at least once for each connection
                      *KERBEROS     - use Kerberos principal name, no prompting
    /ssl        - switch is 0 to turn SSL mode off, or 1 to turn it on
    /5250path   - path to 5250 emulation profiles
                  The /5250path may be set by File->Change Directory... from
                  5250 Session Manager
                  
    *** Note: You can set a maximum of six Hardware Management Interfaces    ***
    ***       Default locations for these may be set in AcsConfig.properties ***
    /HMI1                         - sets the web location for this Hardware Management Interface
    /HMI2                         - sets the web location for this Hardware Management Interface
    /AdminRuntimeExpert           - sets the web location for this Hardware Management Interface
    /AdvancedSystemMgmtInterface  - sets the web location for this Hardware Management Interface
    /CopyServicesManager          - sets the web location for this Hardware Management Interface
    /Db2Mirror                    - sets the web location for this Hardware Management Interface
    /Db2WebQuery                  - sets the web location for this Hardware Management Interface
    /DigitalCertificateMgr        - sets the web location for this Hardware Management Interface
    /DSHMC                        - sets the web location for this Hardware Management Interface
    /HMC                          - sets the web location for this Hardware Management Interface
    /IntegratedVirtualizationMgr  - sets the web location for this Hardware Management Interface
    /SpectrumControl              - sets the web location for this Hardware Management Interface
    /TapeMgmt1                    - sets the web location for this Hardware Management Interface
    /TapeMgmt2                    - sets the web location for this Hardware Management Interface
    /WebHTTPAdmin                 - sets the web location for this Hardware Management Interface

    /del deletes existing system configuration
    /r   replaces existing system configuration

9.1.5 Dump

/PLUGIN=dump  [/<options>]

The logs generated may be accessed from the main GUI by:
    Edit->Preferences
    Local Settings tab
    Dumps Directory

If no options are specified, this function is equivalent to the following function from the main GUI:
    Tools->Generate Service Logs

Valid options are:

    /heapdump - performs the above plus a dump of the JVM heap

9.1.6 Medic

/PLUGIN=medic

The resulting .zip file may be accessed from the main GUI by:
    Edit-Preferences
    Local Settings tab
    Service Directory
This function is equivalent to Tools->Package Service Logs from the main GUI.

9.1.7 Log

/PLUGIN=log  /LEVEL=<Level>
                <Level> is one of the following:
                OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINEST

The logging level may also be set from the main GUI by:
    Edit->Preferences
    General tab
    Logging level

9.1.8 Logon

/PLUGIN=logon    /SYSTEM=<system> [/USERID=<userid>] [/PASSWORD=<password>] [/AUTH] [/C] [/GUI=<1|0>]

    /SYSTEM   - name of system
    /USERID   - user id
    /PASSWORD - password associated with the user id
    /AUTH     - attempts connect to system with specified credentials
                and prompts the user if credentials are not valid or
                not provided.  Caches them on a successful connection.
    /C        - clears the cache
    /C        - clears the cache
    /GUI      - whether or not a graphical user interface can be used

9.1.9 props

/PLUGIN=props

9.1.10 Maint

/PLUGIN=maint [/<options>]

Valid options are:
    /killdaemon     - ends daemon threads.
                      Same as Tools->Reset for Maintenance from main GUI.
                      Setting com.ibm.iaccess.ResetForMaintenanceOnExit=true in AcsConfig.properties
                      will call /killdaemon when Access Client Solutions exits.
    /clearpwcaches  - clears all cached passwords
    /clearjarcache  - clears the product jar cache
    /clearlogs      - clears the Logs Directory at Edit->Preferences
                      Local Settings tab from the main GUI
    /cleardumps     - clears the Dumps Directory at Edit->Preferences
                      Local Settings tab from the main GUI
    /clearsvcdir    - clears the Service Directory at Edit->Preferences
                      Local Settings tab from the main GUI
    /clearsettings  - clears all settings for current user

9.1.11 Ping

/PLUGIN=ping /SYSTEM=<system> [</options>]
    Options include:
        /SSL=<1|0>        Turn SSL on or off
        /ACCEPTALLCERTS=<1|0> Whether or not to automatically add all SSL
                          certificates to the trusted set (when using SSL).
        /SERVERAUTH=<1|0> Turn SSL Server authentication on or off (default is
                          off). This option is disregarded if not testing SSL.
        /GUI=<1|0>        Toggle GUI window on/off (default is off if launched
                          from command-line)
        /PORTS=<port1,port2> A comma-separated list of ports to test. It can be
                numbers or service names (e.g. /PORTS=as-signon,as-sts). If not
                specified, a default set of ports is tested.
                Specifying .CONSOLE will check a list of console specific ports.

        /TIMEOUT=<seconds>   Specify a timeout value, in seconds.

For non-SSL, the following services and ports are checked:

    sshd            22
    telnet          23
    drda           446
    as-svrmap      449
    as-nav        2004
    as-central    8470
    as-database   8471
    as-dtaq       8472
    as-file       8473
    as-netprt     8474
    as-rmtcmd     8475
    as-signon     8476

For SSL, the following services and ports are checked:

    sshd            22
    telnet-ssl     992
    ddm-ssl        448
    as-svrmap      449
    as-nav        2005
    as-central-s  9470
    as-database-s 9471
    as-dtaq-s     9472
    as-file-s     9473
    as-netprt-s   9474
    as-rmtcmd-s   9475
    as-signon-s   9476
 

This function can be launched from the main GUI by:
    System Configurations
    select a system and then Edit
    General tab
    Verify Connection

9.1.12 Sm

/PLUGIN=sm

This is equivalent to 5250 Session Manager from the main GUI.

9.1.13 5250

/PLUGIN=5250 /SYSTEM=<system> [/<options>]

This plug-in starts a 5250 emulator to the specified system.
This function is equivalent to 5250 Emulator from the main GUI.

Valid options are:
    /id=<A-Z>                    - short session id
    /name=<name>                 - session name
    /wsid=<identifier>           - workstation id
    /wide=<1|0|true|false>       - use a wide screen size (27x132)
    /fullscreen<1|0|true|false>  - use the entire screen
    /nosave=<1|0|true|false>     - do not save settings on exit
    /prompt=<1|0|true|false>     - force the configuration dialog to appear
    /port=<port>                 - port number
    /ssl=<1|0|true|false>        - connect using secure sockets
    /sso=<1|0|true|false>        - bypass signon screen
    /kerberos                    - Use Kerberos
    /width=<width>               - initial width of the emulator window
    /height=<height>             - initial height of the emulator window
    /xpos=<xpos>                 - initial x-coordinate position of the top-left
                                   corner of the emulator window
    /ypos=<ypos>                 - initial y-coordinate position of the top-left
                                   corner of the emulator window
    /watermark                   - display system name as watermark on screen
    /watermark=<text>            - display provided text as watermark on screen
    /macro=<macro_name>          - auto-start macro name
     Note: The macro must be in a location defined by the default 5250 session profile.
           The default session profile can be set via Communication->Set As Default Profile
           from any 5250 session.  
    /mparms=<macro_parameters>   - auto-start macro parameters

9.1.14 DTGui

/PLUGIN=dtgui

This plug-in starts the main GUI for Data Transfer.

This function is equivalent to Data Transfer from the main GUI.

9.1.15 Download

/PLUGIN=download [/userid=<userid>] <filename> [<filename> <filename> ...]

    /userid   - user id to use when connecting to the target system
    <filename>- file with the .dtfx extension that was created from a previous
                Data Transfer download.

Data Transfer is also available from the main GUI by selecting Data Transfer.

9.1.16 Upload

/PLUGIN=upload   [/userid=<userid>] <filename> [<filename> <filename> ...]

    /userid   - user id to use when connecting to the target system
    <filename>- file with the .dttx extension that was created from a previous
                Data Transfer upload.

Data Transfer is also available from the main GUI by selecting Data Transfer.

9.1.17 CLDownload

/PLUGIN=cldownload /system=<system>
                          [/userid=<userid>]
                          {/hostfile=<library/filename> | /sql="statement"}
                          {/clientfile=<path><filename>.<extension> | /display}
                          [/<options>]

    /userid     - user id to use when connecting to the target system
    /hostfile   - Source library and file on the IBM i system for the download
                  e.g. /hostfile=QIWS/QCUSTCDT
    /sql        - specify an SQL statement
                  e.g. /sql="select CUSNUM,LSTNAM,INIT,ZIPCOD from QIWS.QCUSTCDT"
    /clientfile - Target file location for the download.
                  The format of this file will be determined by the specified
                  extension (for example, .csv .ods .xls .xlsx)
                  If the file extension is not specified or is of a type
                  not supported, the data will be formatted as a .csv file
    /display    - write the output to the terminal
    
    Valid options are:
       /colheadings=<1/0> - Include column headings as the first row. When specified, the column names will be the heading.
       /usecollabels      - Use column labels for the heading.
       /adjustcolumns     - Adjust column width for .xls and .xlsx files
    

9.1.18 Console

/PLUGIN=console /SYSTEM=<system>

This function is equivalent to 5250 Console from the main GUI.

9.1.19 VCP

/PLUGIN=vcp /SYSTEM=<system>

This function is equivalent to Virtual Control Panel from the main GUI.

9.1.20 L1C

/PLUGIN=l1c /SYSTEM=<system>

This function is equivalent to Navigator for i from the main GUI.

9.1.21 SPLF

/PLUGIN=splf /SYSTEM=<system>

This function is equivalent to Printer Output from the main GUI.

9.1.22 KEYMAN

/PLUGIN=keyman

This function is equivalent to Tools->Key Management from the main GUI.

9.1.23 RMTCMD

/PLUGIN=rmtcmd /SYSTEM=<system>
                  {/CMD="<CL command>" | file=<file_name>}
                  [/noprompt=<1|0>]
                  [/immed=<0|1>]

    /cmd="<CL command>"  - a command to run. Use quotes to avoid spaces from
                           breaking up the command.
    /file=<file_name>    - specify an input file with multiple commands. Commands
                           should be one per line without quotes.
    /noprompt=<1|0>      - when specifying an input file, ignore the results and
                           any prompts before continuing.
    /immed=<0|1>         - send each command as it is read.

This function is only available from the command line.

9.1.24 PWCHANGE

/PLUGIN=pwchange /SYSTEMS=<system,system,system,...>

This function may also be used from the main GUI by selecting the Passwords tab from Edit->Preferences

9.1.25 MIGRATE

/PLUGIN=migrate /<option> /SYSTEM=<system>

<system> can be set to one system name or set to *ALL to indicate all systems.

Valid options are:
    /IMPORT - Copy one (or all) system configurations from the legacy Windows
              configuration to IBM i Access Client Solutions.
    /EXPORT - Copy one (or all) system configurations to the legacy Windows
              configuraiton from IBM i Access Client Solutions.
    /DELETE - Delete one (or all) system configurations from the legacy Windows
              configuration.

This function may also be used from the main GUI by selecting File->Copy Connections

9.1.26 RESTRICT

/PLUGIN=restrict /<options>

 Valid options are:
     /restrict=<func1,func2,func3>   Restricts the given functions on this
                                     workstation.
     /unrestrict=<func1,func2,func3> Allows the given functions on this
                                     workstation.
     /list                           Lists whether functions are allowed or
                                     restricted on this workstation.
     /export=<file>                  Export restrictions to the named file with
                                     a .acsr file extension.
     /import=<file>.acsr             Import restrictions from a file with
                                     a .acsr file extension.
     /exportreg=<file>               Export a Windows registry file (.reg file).

This plug-in provides the capability to anyone with administrator or root authority to restrict certain functions from all users on the current workstation.

   Function           Description
    5250            5250 Emulator
    cfg             System Configurations
    checkupdates    Check for available updates
    checkversion    Return the current version
    cldownload      Data Transfer command-line downloads
    console         5250 Console
    consoleprobe    Search the local network for console configurations
    db2             Schemas
    db2tools        SQL Performance Center
    download        Data Transfer command-line downloads
    dtgui           Data Transfer graphical user interface
    hmcprobe        Search an HMC for partitions
    ifs             Integrated File System
    installupdates  Install updates from an IBM i configured location
    keyman          SSL/TLS certificate management
    l1c             IBM Navigator for i (Level 1 Console)
    osssetup        Open Source Package Management
    restrictview    Restrict view of currently restricted functions
    rmtcmd          Remote command (available from the command-line)
    rss             Run SQL Scripts
    sm              5250 Session Manager
    splf            Printer Output (spool files)
    ssh             Secure Shell
    sysdbg          IBM i System Debugger
    upload          Data Transfer command-line uploads
    vcp             Virtual Control Panel


    Hardware Management Interfaces:
    hmi1            Hardware Management Interface 1 (*footnote)
    hmi2            Hardware Management Interface 2
    asmi            Advanced System Management Interface (ASMI)
    csmi            Copy Services Manager for i
    dcm             Digital Certificate Manager
    dshmc           DS HMC
    hmc             Hardware Management Console (HMC)
    httpadmin       Web (HTTP) Administration for i
    ivm             Integrated Virtualization Manager
    specctrl        Spectrum Control
    tapemgmt1       Tape Management 1
    tapemgmt2       Tape Management 2
    are             Administration Runtime Expert
    db2webquery     Db2 Web Query
    

Functions may also be excluded as a group using keywords:

   Group              Functions
  dataxfer          dtgui,upload,download,cldownload
  emulator          sm,5250
  keyman            keyman
  opconsole         console,vcp,consoleprobe,hmcprobe
  rmtcmd            rmtcmd
  splf              splf
  ifs               ifs
  hwconsole         hmi1,hmi2,asmi,csmi,dcm,dshmc,hmc,httpadmin,ivm,specctrl,tapemgmt1,tapemgmt2,are,db2webquery
  l1cplugin         l1c
  database          db2,rss,db2tools
  debugger          sysdbg

For an easy way to restrict functions on multiple workstations, see section 9.5 Customized Packages.

9.1.27 RESTRICTVIEW

/PLUGIN=restrictview

9.1.28 FILEASSOC

/PLUGIN=fileassoc [<filetype> <filetype> ...] [/c]

    <filetype>   - valid file types are:  dttx, dtfx, hod, bchx, ws, bch, sql
    /c           - clear the file association for the specified file types

This function is equivalent to Tools->File Associations from the main GUI.

9.1.29 DTBATCH

/PLUGIN=dtbatch [/userid=<userid>] <filename> [<filename> <filename> ...]

    /userid   - user id to use when connecting to the target system
    <filename>- file with the .dtfx or .dttx extension that was created from a
                previous Data Transfer download or upload.
                Multiple files may be specified with or without this keyword.

Data Transfer is also available from the main GUI by selecting Data Transfer.

9.1.30 PM5250

/PLUGIN=pm5250 [/input=<file> ...  /output=<directory>] [/verbose] [/gui]

    /input    - Files to be migrated.  The files must be 5250 files with
                an extension of .ws, .bch, .kmp, .pmp, or .bar.
    /output   - location where migrated files will be stored.
    /verbose  - display results of migrated files.
    /gui      - start the user interface for migrating 5250 files.

9.1.31 RSS

/PLUGIN=rss /SYSTEM=<system> /DATABASE=<database> [/FILE=<file>] [/SQL="statements"] [/AUTORUN=<0,1>]

    /FILE      - Open the specified file of SQL statements
    /SQL       - specify SQL statements
                 e.g. /SQL="select CUSNUM,LSTNAM,INIT,ZIPCOD from QIWS.QCUSTCDT"
    /AUTORUN   - Automatically run the script (0=false, 1=true)

9.1.32 DB2TOOLS

/PLUGIN=DB2TOOLS /SYSTEM=<system> /DATABASE=<database> [Options]

Valid options are:
    /ACTION=<LIST | ANALYZE | STATEMENTS | COMPARE>
                    - Action to perform:
                      The LIST option can be used with the LISTNAME argument and displays the
                      SQL Performance Center with the specified list.
                      The ANALYZE option analyzes the given performance data set.
                      The STATEMENTS option shows statements for either the SQL plan cache or
                      the given performance data set.
                      The COMPARE option compares the given performance data set(s).
    /NAME=<name>    - The name of the performance data set
    /TABLE=<name>   - The name of the table that contains performance data
    /SCHEMA=<name>  - The name of the schema of the table that contains performance data
    /LISTNAME=<DBMONITORS | PCEVENTMONITORS | PCSNAPSHOTS | LIVE_PLAN_CACHE>
                    - The initial list to display in the SQL Performance Center.

• Analyze - Provides a summarized view of collected performance data that serves as a launchpoint into deeper analysis using drill-down navigation.
• Compare - View a summary comparison of two or more performance data collections, then choose two for a deeper statement comparison.
• Show Statements - Work with SQL statements in the SQL Plan Cache or in a performance data collection.
• Visual Explain - Generate a graphical representation of the statement execution plan to see exactly how your SQL statements work.
• SQL Plan Cache - Manage the settings of the system SQL Plan Cache.

9.1.33 IFS

/PLUGIN=ifs /SYSTEM=<system>

• Copy objects between your client system and your IBM i
• Copy objects within the Integrated File System on an IBM i or to the Integrated File System on another IBM i
• Send objects to another IBM i (or to several)
• Create new folders (directories, libraries, and folders)
• Delete objects
• Rename objects
• View properties of objects

9.1.34 DB2

/PLUGIN=DB2 /SYSTEM=<system>

9.1.35 CHECKUPDATES

/PLUGIN=checkupdates

9.1.36 SSH

/PLUGIN=SSH /SYSTEM=<system>

9.1.37 OSSSETUP

/PLUGIN=OSSSETUP

9.1.38 INSTALLUPDATES

/PLUGIN=installupdates [Options]

Valid options are:
    /noprompt         Do not prompt for user id and password
                      Note: When using this option, if the user's credentials to the remote system
                            are already cached, the check for available updates will continue normally.
                            If the user's credentials are not cached, authorization to the remote
                            system will be denied and updates will not be available.

9.1.39 HTTPPROXYUI

/PLUGIN=httpproxyui

9.1.40 UDC Font Conversion

/udcnv  [/wide]

    /wide         This option is only valid with code page 932.
                  When specified, the font-image file produced will contain unicode characters.

      Start_Programs\Windows_x86-64\acslaunch_win-64.exe /udcnv

  Code Page     Platform                        Font-image filename
     932        Japanese Windows                     jpn24.fnt
     949        Korean Windows                       kor24.fnt
     936        Simplified Chinese Windows           chs24.fnt
     950        Traditional Chinese Windows          cht24.fnt

      <Configuration Root>\Emulator\fonts

       C:\Users\<user_name>\Documents\IBM\iAccessClient

Limitations:

• In a Traditional Chinese Windows environment, there are 13 more UDCs than IBM's Big5 UDCs. Therefore, if the last 13 UDCs are defined in the range of 0xC8F2-0xC8FE, they are ignored by the utility and cannot be used.
• In a Korean Windows environment, only local code page 949 is supported. You can define and print 188 UDCs in the ranges of 0xC9A1-0xC0FE and 0xFEA1-0xFEFE.

9.1.41 CHECKVERSION

/PLUGIN=checkversion

9.2 File Associations

Some configuration files generated by IBM i Access Client Solutions are supported from the command-line when they are provided as the first and only parameter. When these files with specific file extensions are provided as the first parameter, IBM i Access Client Solutions will associate the file with the function to be invoked and provide the file as input to that function.

The following extensions have file association support:

    .dttx   - Data Transfer upload request
    .dtfx   - Data Transfer download request
    .hod    - 5250 emulator session profile
    .bchx   - multiple session emulation profile
    .ws     - 5250 emulator session profile (Personal Communications)
    .bch    - multiple session emulation profile (Personal Communications)
    .sql    - SQL file

    acslaunch_xxx dt_download_file.dtfx - runs the saved download operation
    acslaunch_xxx dt_upload_file.dttx   - runs the saved upload operation
    acslaunch_xxx system_lp13ut20.hod   - starts a 5250 session to the system

These supported command-line file associations enable the user to manually set up operating system (OS) specific file associations. Since file associations are platform dependent, the steps required depend on the OS.

The following sections provide some examples of setting up file associations for some operating systems.

9.2.1 File Associations (for Windows)

1. From the main GUI menu bar, select Tools->File Associations...
2. Select the file types you want to create file associations for.
3. Select OK

The appropriate IBM i Access Client Solution function will now run when you double-click files with this type.

9.2.1.1 Change Icon (for Windows Shortcut)

1. Locate the shortcut previously created for the binary file appropriate for your hardware architecture (acslaunch_win-64.exe OR acslaunch_win-32.exe)
2. Right-click and select Properties
3. Select the Shortcut tab
4. Click the Change Icon... button
5. Select the icon to be used for this shortcut
6. Select OK
7. Select OK

9.2.2 Setting up a Desktop Icon (for Linux)

Follow the steps in the QuickStartGuide for Linux. This will install the application to /opt/ibm/iAccessClientSolutions. It will also create: /usr/share/applications/IBM i Access Client Solutions.desktop

To create an icon for the product on your desktop, copy the above .desktop file to your Desktop folder. You may need to adjust the permissions of file on your desktop so that it is executable.

9.2.2.1 File Associations (for Linux)

The steps required for setting file associations will depend on the Linux distribution and the desktop environment being used. In general, the steps required are similar to the above steps used for Windows.

1. Locate a file you want to associate that contains a supported extension (e.g. .hod, .bchx, .dtfx, or .dttx)
2. Right-click the file. Look for options or properties that allow you to associate a program with the file.
3. Associate the file and/or its extension with the appropriate IBM i Access Client Solutions binary file or launch script.

9.2.3 File Associations (for Mac)

In order to use File Associations on a Mac, the file type must be associated with an application. Follow the steps in the QuickStartGuide for Mac so IBM i Access Client Solutions is an installed application.

9.2.3.1 Create File Associations (for Mac)

1. Use Finder to locate a file you want to associate that contains a supported extension (e.g. .hod, .bchx, .dtfx, or .dttx)
2. Select the file and then File->Get Info
3. Under the "Open with:" option select Other
4. Browse to the location of the IBM i Access Client Solutions application.
5. Select the application.
6. Check the box to Always Open With. Select Add.
7. Back at "Open with:" select Change All. Select continue to any dialog.

The appropriate IBM i Access Client Solution function will now run when you double-click files with this type.

9.2.3.2 Change Icon (for Mac)

Use the Preview application to locate the Icons folder within the product directory and use Finder to replace the icon in Get Info.

1. From Preview, select File->Open
2. Locate the product Icons directory
3. Select the file that contains the Icon and then Open
4. Select Edit->Select All
5. Select Edit->Copy
6. From Finder, locate the .hod, .bchx, .dtfx, or .dttx file whose icon is to be changed.
   If the file is already on your desktop, click it to select it. Otherwise, Select Go->Go To Folder and then enter the path to the file and then Go.
   Click the file to select it.
7. File->Get Info
8. Click the icon at the top of Get Info
9. Edit->Paste

9.3 Changing Configuration Location

By default, each user will have their own unique location for their configuration. The configuration location can be changed by setting the property:
    com.ibm.iaccess.AcsBaseDirectory
This property exists inside the AcsConfig.properties file.

The AcsConfig.properties file exists in two locations when the product is shipped. It is contained inside the acsbundle.jar file. For convenience, it is also provided in the product .zip file and is in the same directory as the acsbundle.jar file when the .zip file is unpacked.

During start-up, the product will only use the first AcsConfig.properties file it finds. It first checks the directory where the acsbundle.jar file exists. If AcsConfig.properties is not found in the same directory as the acsbundle.jar file , it will use the AcsConfig.properties file inside the acsbundle.jar file.

You may choose to update AcsConfig.properties in acsbundle.jar with a custom configuration path. If you do, make sure the directory where acsbundle.jar exists does not contain an AcsConfig.properties file or it will get used instead. This provides the flexibility of being able to distribute the configuration location with the acsbundle.jar file while also providing the flexibility to override it.

Special keywords are provided which can be used when defining the configuration path. When the keywords are used in the specified path, the keywords are substituted with the text or path they define. Only one keyword can be used in the configuration path. The special keywords and their meanings are:

    {USER} - The current user ID. This keyword can be anywhere in the path

The following keywords can only be at the beginning of the specified path:

   {PRODUCTDIR} - the path to the same directory as acsbundle.jar
    {TEMPDIR}    - the path to a platform specific temporary directory
    {ROOT}       - the path to the root of the file system
    {HOME}       - the path to the user's home directory
    {DEFAULT}    - the default path the product would normally use

Technical Note:
We do not recommend sharing a configuration between multiple users. For example, if X were a shared network drive, the following setting may cause unpredictable results:

    com.ibm.iaccess.AcsBaseDirectory=X:/Shared_Network_drive/config_directory

There are several problems with multiple users sharing this configuration path:

1. Unpredictable results will occur if multiple users simultaneously use the configuration.
2. This example assumes each user has the X drive mapped to the same location.
3. Using a network drive in the configuration would not work from a Linux or Mac client. Using the provided keywords, as in the examples below, work on Windows, Linux and Mac.

When sharing a configuration path between multiple users, the {USER} keyword should be used to avoid collisions with other users. It is substituted with the user ID of the current user.

When setting the configuration path, use a forward slash ('/') instead of a backward slash ('\') as the directory separator. This works on all operating systems including Windows.

Here are some recommended sample configurations:

Example 1 - local configuration for current user (default):

    com.ibm.iaccess.AcsBaseDirectory=

Example 2 - remote (or local) configuration unique for each user:

    com.ibm.iaccess.AcsBaseDirectory={ROOT}/config_directory/{USER}/

Example 3 - remote (or local) configuration unique for each user:

    com.ibm.iaccess.AcsBaseDirectory={PRODUCTDIR}/config_directory/{USER}/

Example 4 - local configuration on portable media (like USB drive):

    com.ibm.iaccess.AcsBaseDirectory={PRODUCTDIR}/config_directory

9.4 Other Deployment Options

Here are some other deployment options you may want to consider:

• Deploy the product in a single location where it can be accessed by several users.
• Automatically import configuration settings. See section 9.4.1
• Deploy natively on the IBM i. See section 9.4.2

9.4.1 Automatically import configuration settings

The following properties may be used in the AcsConfig.properties file to automatically set up a configuration for new users or to update a configuration for existing users:

   com.ibm.iaccess.autoimport
   com.ibm.iaccess.autoimport.version

Here are the necessary steps:

1. Create the configuration you want to propagate to one or more users.
2. Export the configuration to a file using File->Export Configuration from the main GUI or use the command line option in section 9.1.1 Backup.
3. Move the configuration file to the desired location. There are several available options described later.
4. Set the com.ibm.iaccess.autoimport property in AcsConfig.properties to the path of the configuration file.
5. Set the com.ibm.iaccess.autoimport.version to an integer value that represents the version of the configuration file.

Here is how it works:
The saved configuration referenced by the com.ibm.iaccess.autoimport property is automatically imported when the integer value of the com.ibm.iaccess.autoimport.version property mismatches the last value that was imported. In addition to providing a way to set up an initial configuration and provide updates to an existing configuration, this also provides a way to back-level a configuration. The configuration is updated anytime there is a mismatch between the integer value of the version property with the last version that was imported. However, while an imported configuration may change the configuration for an existing system in the user's configuration, a system will never be deleted from the user's configuration.

The path for the com.ibm.iaccess.autoimport property may be specified as an absolute path, a URL or with keywords defined in section 9.3. For example:

    com.ibm.iaccess.autoimport=C:/acs_bak.zip

    com.ibm.iaccess.autoimport=file///C:/acs_bak.zip

    com.ibm.iaccess.autoimport=http://your.company.com/path/file/acs_bak.zip

    com.ibm.iaccess.autoimport=ftp://your.company.com/path/file/acs_bak.zip

    com.ibm.iaccess.autoimport={PRODUCTDIR}/acs_bak.zip

Additional flexibility is provided by allowing the configuration file to be distributed within acsbundle.jar or in the same directory as acsbundle.jar. For either case, set com.ibm.iaccess.autoimport with the name of the file without a preceding path:

    com.ibm.iaccess.autoimport=acs_bak.zip

A special value of * is allowed for com.ibm.iaccess.autoimport.version:

    com.ibm.iaccess.autoimport.version=*

This will always import the configuration regardless of any previous version.

Note:
To avoid importing the default user name specified on the Connection tab of a System Configuration, place the following property in the AcsConfig.properties file.

    com.ibm.iaccess.ResetDefaultUserOnImport=true

9.4.2 Native IBM i Deployments

Some of the command-line plug-ins that do not require a GUI can be used natively on the IBM i. For example, you can use Data Transfer to extract data from your database into a spreadsheet file type directly on the IBM i without downloading the data to the PC.

To do this, you can extract the product .zip file to any place in the IBM i Integrated File System (IFS). For example, if you extracted the product .zip file to:

 /home/AccessClientSolutions 

 /some_path/qcustcdt.dtfx 

QSH CMD('java -jar /home/AccessClientSolutions/acsbundle.jar /PLUGIN=dtbatch /some_path/qcustcdt.dtfx')                                            

Note:
There are also IBM i PTFs which will extract the contents of the product for you on an IBM i. See section 5.3 Optional IBM i PTFs

9.5 Customized Packages

IBM i Access Client Solutions provides system administrators the ability to restrict the usage of specific functions by setting either of the following two properties in the AcsConfig.properties file:

    com.ibm.iaccess.ExcludeComps=<function, function,...>
    com.ibm.iaccess.IncludeComps=<function, function,...>

Setting com.ibm.iaccess.ExcludeComps will disable the specified functions. All other functions are enabled. Any function specified on this property will not be available from the main ACS GUI nor from the command line. The functions which may be specified on this property are listed below.

Setting com.ibm.iaccess.IncludeComps will enable the specified functions. All other functions are disabled. Any function specified on this property is available for normal usage. The functions which may be specified on this property are listed below.

   Function           Description
    5250            5250 Emulator
    cfg             System Configurations
    checkupdates    Check for available updates
    cldownload      Data Transfer command-line downloads
    console         5250 Console
    consoleprobe    Search the local network for console configurations
    db2             Schemas
    db2tools        SQL Performance Center
    download        Data Transfer command-line downloads
    dtgui           Data Transfer graphical user interface
    hmcprobe        Search an HMC for partitions
    ifs             Integrated File System
    keyman          SSL/TLS certificate management
    l1c             IBM Navigator for i (Level 1 Console)
    osssetup        Open Source Package Management
    restrictview    Restrict view of currently restricted functions
    rmtcmd          Remote command (available from the command-line)
    rss             Run SQL Scripts
    sm              5250 Session Manager
    splf            Printer Output (spool files)
    ssh             Secure Shell
    sysdbg          IBM i System Debugger
    upload          Data Transfer command-line uploads
    vcp             Virtual Control Panel

    Hardware Management Interfaces:
    hmi1            Hardware Management Interface 1 (*footnote)
    hmi2            Hardware Management Interface 2
    asmi            Advanced System Management Interface (ASMI)
    csmi            Copy Services Manager for i
    dcm             Digital Certificate Manager
    dshmc           DS HMC
    hmc             Hardware Management Console (HMC)
    httpadmin       Web (HTTP) Administration for i
    ivm             Integrated Virtualization Manager
    specctrl        Spectrum Control
    tapemgmt1       Tape Management 1
    tapemgmt2       Tape Management 2
    are             Administration Runtime Expert
    db2webquery     Db2 Web Query
    

Functions may also be specified as groups using the following keywords:

   Group              Functions
  dataxfer          dtgui,upload,download,cldownload
  emulator          sm,5250
  keyman            keyman
  opconsole         console,vcp,consoleprobe,hmcprobe
  rmtcmd            rmtcmd
  splf              splf
  ifs               ifs
  hwconsole         hmi1,hmi2,asmi,csmi,dcm,dshmc,hmc,httpadmin,ivm,specctrl,tapemgmt1,tapemgmt2,are,db2webquery
  l1cplugin         l1c
  database          db2,rss,db2tools
  debugger          sysdbg

Normally these properties would not be used together. If they are used together and a function is specified on both properties, the function is disabled.

Example 1: This will disable all the functions associated with OPCONSOLE,HWCONSOLE,L1CPLUGIN. All other functions in the above list are enabled.

     com.ibm.iaccess.ExcludeComps=OPCONSOLE,HWCONSOLE,L1CPLUGIN   

Example 2: This will enable 5250 and data transfer downloads. All other functions in the above list are disabled.

     com.ibm.iaccess.IncludeComps=5250,DOWNLOAD  

If the system administrator would like to update the AcsConfig.properties file inside acsbundle.jar before deploying it to their users, an example of how to do that is:

    jar uvf acsbundle.jar AcsConfig.properties

9.6 Migrating from IBM i Access for Windows

IBM i Access Client Solutions configuration files are not compatible with the corresponding functions in IBM i Access for Windows. IBM i Access Client Solutions provides a migration path for several key items as discussed in the following sections.

9.6.1 Migrating System Configurations

The Copy Connections function available from the main GUI menu at File->Copy Connections provides an interface for copying system configurations between IBM i Access Client Solutions and the legacy Windows configuration supported by IBM i Access for Windows. For additional information, see the help for the main panel of Copy Connections. The system configurations may also be migrated using the command line. See section 9.1.25 MIGRATE for additional information.

9.6.2 Migrating 5250 Emulation

5250 emulation files used by the IBM i Access for Windows Personal Communications emulator can be converted by using the 5250 Session Manager in IBM i Access Client Solutions. The following file types can be converted from Personal Communications:

   .ws   - emulator profile
   .bch  - emulator batch file
   .kmp  - keyboard customization file
   .pmp  - poppad files
   .bar  - menu bar files

   .hod  - emulator profile
   .bchx - emulator batch file
   .kmp  - keyboard customization file
   .pmp  - poppad files
   .bar  - menu bar files

The conversion of these files can be initiated from the IBM i Access Client Solutions Session Manager menu by:

• selecting File->Import and then locating the Personal Communications files.
• dragging and dropping the file into the IBM i Access Client Solutions Session Manager window.

A macro conversion utility is available. From the Session Manager:

    Tools->Convert Macro...

9.6.3 Migrating Saved Data Transfer Request Files

Data Transfer in IBM i Access Client Solutions provides a wizard for converting saved Data Transfer request files that were generated by IBM i Access for Windows.

The following file types can be converted from IBM i Access for Windows:

   .dtf - data transfer from IBM i
   .dtt - data transfer to IBM i

   .dtfx - data transfer from IBM i
   .dttx - data transfer to IBM i

The Data Transfer migration wizard is available from the Data Transfer main menu by selecting Actions->Data Transfer Migration

9.6.4 EHLLAPI

For 5250 applications which leverage EHLLAPI when accessing the Personal Communications emulator shipped with IBM i Access for Windows, refer to the following KB article for information about using EHLLAPI with IBM i Access Client Solutions:

    http://www-01.ibm.com/support/docview.wss?uid=nas8N1010639

9.6.5 Kerberos

IBM i Access Client Solutions has support for Kerberos. To use Kerberos when connecting to a system:

1. Bring up System Configurations from the main GUI
2. Select New or Edit an existing system configuration
3. On the Connection tab, select
   "Use Kerberos authentication; do not prompt"

9.6.6 5250 Compatibility

The property com.ibm.iaccess.PC5250Compatibility can be used to change the default behavior for the ACS emulator. This property can be set in AcsConfig.properties with the following values:

    allowNnAsFKeyHotspot      - treat NN hotspots (eg FNN, PFNN, FPNN) like function key hotspots.
    allowHighlightBypassField - allow bypass fields with ENTFLDATR to be highlighted.
    allowTypingInSignPosition - allow '-' or ' ' to be keyed in the sign position of a signed numeric field.
    allowTransformSpecialCharsOnPaste - change how certain characters get transformed when pasting text 
                                        from external documents (eg curly quotes become straight quotes).

     com.ibm.iaccess.PC5250Compatibility=allowTransformSpecialCharsOnPaste

     com.ibm.iaccess.PC5250Compatibility=allowNnAsFKeyHotspot,allowHighlightBypassField,allowTypingInSignPosition

9.7 Key Management

Managing certificates for Secure Socket Layer (SSL) connections is available from the main GUI by selecting Tools->Key Management. Some tasks on the Key Database require the keystore integrity passphrase.

9.8 Data Transfer

9.8.1 Data Transfer Support for Excel and Calc Spreadsheets

In addition to supporting downloads to a File, Data Transfer also supports downloads to an active spreadsheet for either Microsoft's Excel spreadsheet or OpenOffice's Calc spreadsheet. To download to an active spreadsheet, the main Data Transfer GUI panel provides the option to select an Output Device. By default, the Output Device is File. If your platform supports interaction with the Excel and/or Calc spreadsheet, additional options for an Active Excel Spreadsheet and an Active Calc Spreadsheet can be selected from the Output Device drop down box.

Restrictions:

• A minimum version of OpenOffice 3.4.1 is required on Windows.
• A minimum version of OpenOffice 4.2.1 is required on Linux and Mac and must be installed to the default location.
• IBM i Access Client Solutions running on Linux or Mac only supports interaction with OpenOffice.
  IBM i Access Client Solutions running on Windows supports interaction with either Microsoft Excel or OpenOffice Calc.
• The bitness of OpenOffice must match the bitness of IBM i Access Client Solutions.
  Explanation: OpenOffice is available in both 32bit and 64bit versions. Both versions are capable of running on a 64 bit PC. When interacting with an OpenOffice spreadsheet, the bitness of OpenOffice and IBM i Access Client Solutions must be the same or Data Transfer will not be able to interact with the spreadsheet. The bitness of IBM i Access Client Solutions is determined by the Java Virtual machine (JVM) where it is running. When there is a bitness mismatch between OpenOffice and the JVM running IBM i Access Client Solutions and you select an active spreadsheet for the Output Device, an error similar to "Active Spreadsheet was not found" is displayed. If you are running on a 64 bit PC, you may start IBM i Access Client Solutions using either the 32 bit or 64 bit binary launcher specific to your platform. In order for the active spreadsheet support to work, start IBM i Access Client Solutions using the platform specific binary that matches the bitness of the OpenOffice application being used.
  Since Mac only supports a 64 bit JVM, you must install the 64 bit version of OpenOffice in order to use the active spreadsheet support on Mac.

9.8.2 Data Transfer Support for Character Truncation and Numeric Overflow

During a Data Transfer upload request, if a character or numeric field exceeds the defined size of the field, the upload request will terminate.

To enable character fields to be truncated from the end, set the following property in the AcsConfig.properties file:
    com.ibm.iaccess.dataxfer.jdbc.AllowCharacterTruncation=true

To enable numeric fields to be set to their maximum positive or negative value when the provided numeric field exceeds the defined boundary, set the following property in the AcsConfig.properties file:
    com.ibm.iaccess.dataxfer.jdbc.AllowNumericOverflow=true

When these properties are set to true, the upload request will continue without providing any indication that truncation or overflow occurred. Character fields are truncated at the end. Numeric fields are set to their maximum value for overflow and their minimum value for underflow.

Alternatively, the above properties can be set from from the command line like other Java properties as follows:
    -Dcom.ibm.iaccess.dataxfer.jdbc.AllowCharacterTruncation=true
    -Dcom.ibm.iaccess.dataxfer.jdbc.AllowNumericOverflow=true

9.8.3 Data Transfer Sheet Name

During downloads, a sheet name is generated based on the name of the IBM i source library and file with ">Sheet#" appended where # is replaced with the appropriate sheet number. For example:
    qiws.qcustcdt>Sheet1

To override the library and file portion of the sheet name, you may specify the following property:
    com.ibm.iaccess.dataxfer.SheetId=your_string
This will generate:
    your_string>Sheet1

If the special values of %1$s %2$s or %3$s are used in the property, the placement of library.filename and sheet# can be changed or eliminated.

The values have the following meaning:

            %1$s - library.filename    For example: qiws.qcustcdt
            %2$s - sheet#                   For example: 1
            %3$s - destination file name without file extension

Using any of these special values provides complete control of the sheet name.

Setting the property to Sheet%2$s will produce sheet names: Sheet1, Sheet2, etc
com.ibm.iaccess.dataxfer.SheetId=Sheet%2$s

You may use %1$s %2$s or %3$s in any combination with other text.

Note:
Since sheet names in a spreadsheet must be unique, setting the property to use %1$s or %3$ without also using %2$s will produce an error if more than one sheet is needed.

9.9 Establishing a Console Connection to IBM i

To perform administrative functions on the IBM i, a 5250 console is required. IBM i Access Client Solutions supports both LAN and HMC console configurations.

If you know the Service host name or Service IP address for your IBM i or the host name or IP address for your HMC console, you can configure the console information within IBM i Access Client Solutions using the following steps:

1. Start IBM i Access Client Solutions on your PC.
2. On the main panel, click System Configurations.
3. Click the New button to enter a new configuration or the Edit button to update an existing configuration
4. Select the Console tab
5. Enter the appropriate information for your console type.

For an IBM i where the console configuration does not yet exist (e.g. a new system just delivered to your business), an IP address for a console connection is automatically assigned in the range of 169.254.62.0 - 169.254.62.63 during the IPL. For these cases, the following steps will help establish a console connection using IBM i Access Client Solutions:

1. Disable your PC's wireless connectivity. The following steps require the wired Ethernet port.
2. Run an Ethernet cable between your PC and the IBM i T1 port.
3. Start IBM i Access Client Solutions on your PC.
4. On the main panel, click System Configurations.
5. From System Configurations, click the Locate Console... button.
6. From the IBM i Locator panel, click the Search button.
7. If the IPL sequence on the IBM i has progressed far enough for the automatic IP address to be a assigned, the IP address should be displayed on the Search panel.
8. Click the displayed IP address to select it, then click the Console button to connect a 5250 console.
9. A panel will appear asking for Service Tools credentials.
10. Upon entering valid credentials, a 5250 console is displayed.
11. The console can be used to handle initial install and setup tasks.

When you are ready to add the IBM i system to the rest of your network infrastructure, there is additional information in the IBM Knowledge Center for how to configure the Service Tools LAN adapter:

See Configuring the service tools server for DST.

For IBM i systems that already have a LAN console configuration and are already in your network infrastructure, the following steps may be used to find existing console configurations:

1. Start IBM i Access Client Solutions on your PC.
2. On the main panel, click System Configurations.
3. From System Configurations, click the Locate Console... button.
4. On the IBM i Locator panel, update the Near field to an IP address in the range you want to search.
5. Click the Search button to find LAN consoles in the specified range.
6. Click the displayed IP address to select it, then click the Console button to connect a 5250 console.
7. A panel will appear asking for Service Tools credentials.
8. Upon entering valid credentials, a 5250 console is displayed.

9.10 Additional Fonts

Additional fonts for 5250 emulation may be added to the Fonts directory.

To provide alternative and/or multiple locations for additional fonts, set the com.ibm.iaccess.Fonts property located in the AcsConfig.properties file.

The default Fonts directory may be overridden by setting the com.ibm.iaccess.Fonts property to a:

1. <path> which is a directory containing fonts
2. <path>/<filename> of a specific font file (e.g. .ttf)
3. URL to a font file
4. a semi-colon delimited list of any of the above

Note:
The <path> may be an absolute path or a relative path starting from the location of acsbundle.jar. Only monospaced fonts are recognized by 5250 emulation.

Example 1 (default):

     com.ibm.iaccess.Fonts=Fonts   

     com.ibm.iaccess.Fonts=/Users/All/Fonts;Fonts

9.11 Using Credentials from a netrc File

To enable the usage of a .netrc file (Linux and Mac) or a _netrc file (Windows), go to the IBM i Access Client Solutions main GUI and from the menu bar, select
    Edit->Preferences
    General tab
    Check the box: Read netrc file for login information
    Click the Apply button
    Restart IBM i Access Client Solutions

The standard format of a netrc file is:

     machine <system> login <user-id> password <password>

The netrc file must be stored in the user's home directory and the system name and user-id must match System Configurations. From IBM i Access Client Solutions:
    Select System Configurations
    Select and then Edit the system
    Connections tab
    Select Use default user name to prompt once for each system
    Fill in the user-id for: Default user name
    Select OK

When the system name and Default user name match the contents of the netrc file, a connection to the system is made using the password from the netrc file without prompting the user.

9.12 Integrated File System (IFS)

9.12.1 IFS, QFileSvr.400, and Security

The Integrated File System Support uses the QFileSvr.400 file system to copy or send objects from one IBM i partition to another. This means the user profile and password on both partitions must match, and the partitions must have the same password level system value (QPWDLVL). If using Kerberos authentication, both partitions must have Network Authentication Service and Enterprise Identity Mapping (EIM) configured. For more details, see IBM i file server file system (QFileSvr.400).

By default, the connections to other IBM i partitions made by the QFileSvr.400 file system are not secure. There are two options for configuring a secure connection:

Option 1:
Configure QfileSvr.400 to be secure. See Securing QFileSvr.400 file system connections.

Option 2:
Use the client PC as a bridge between the two IBM i partitions. System Configurations must have the "Use SSL for connection" option selected for both partitions, and the following property must be set in the AcsConfig.properties file:
    com.ibm.iaccess.ifs.transferMechanism=ACS
Alternatively, the property can be set from from the command line like other Java properties as follows:
-Dcom.ibm.iaccess.ifs.transferMechanism=ACS

9.12.2 IFS Authority

The Integrated File System support requires authority to use the following CL commands:

    CPY
    CPYFRMSTMF
    CPYTOSTMF
    CRTDIR
    CRTLIB
    CRTSAVF
    RMVDIR
    RST
    SAV
    SETASPGRP
 

If the user cannot use these CL commands, the Copy, Paste, Send, Delete, and New Folder actions will fail.

9.12.3 IFS Limitations

The Integrated File System support does not allow actions for objects which have paths that start with /QFileSvr.400, /QNTC, or /QOPT. If the current directory path or any selected object path starts with /QFileSvr.400, /QNTC, or /QOPT, all items in the Actions menu are disabled and a context menu will not be displayed.

9.12.4 IFS and Independent ASPs

The Integrated File System support does not allow the Copy, Paste, or Send action when the source object or target path is located on an independent ASP.

9.12.5 IFS Performance

Performance of IFS when displaying the contents of a directory is determined by the column attributes selected (View->Columns...) and whether the directory contains symbolic links. For non-symbolic links, there is an additional performance impact when selecting either CCSID or Owner. For symbolic links, there is an additional performance impact for each column attribute selected other than Icon, Name, and Size (KB)

Note: Size (KB) for symbolic links is not displayed when browsing the directory. Select Properties to get the size of the file represented by the symbolic link.

When displaying a directory with a large number of entries, you may exceed the default memory limit of the Java Virtual Machine (JVM) where IBM i Access Client Solutions is running. This can cause all open windows to slow down and eventually stop responding. If you are displaying directories with a large number of entries, consider using the Include filter to limit the number of entries sent from the server. Or, start the product using the -Xmx option to increase the available memory. For example:

    java -Xmx4g -jar V:/some_location/acsbundle.jar
or
    Start_Programs\Windows_x86-64\acslaunch_win-64.exe -Xmx4g

The above examples will change the JVM memory to 4 gigabytes. You may need to increase the size even more based on the number of entries in the directory.

9.13 Secure Shell (SSH) Terminal

For platforms where a Secure Shell exists by default or has been installed, the SSH Terminal feature will appear on the IBM i Access Client Solutions main GUI. SSH Terminal will launch a terminal emulator to the IBM i Integrated File System.

Most Mac, Linux, and other UNIX-derived systems already have a Secure Shell by default. For these platforms, it is assumed an OpenSSH client exists and is located at /usr/bin/ssh. Windows users will need to install one of the Secure Shells available for Windows.

Secure Shells supported by IBM i Access Client Solutions:

         Linux:       Xterm, XterminalEmulator, MateTerminal, Terminator, GnomeTerminal, Konsole, Xfce4
         Mac:         Terminal, iTerm2
         Windows: cygwin, PuTTY, bash
                          cygwin requires the OpenSSH package to be installed
                          bash is available as part of the Linux subsystem for Windows

If there are multiple SSH applications installed, you can use the com.ibm.iaccess.PreferredSSHClient property to set the preferred SSH client.

Linux examples:
         com.ibm.iaccess.PreferredSSHClient=XterminalEmulator
         com.ibm.iaccess.PreferredSSHClient=MateTerminal
         com.ibm.iaccess.PreferredSSHClient=Terminator
         com.ibm.iaccess.PreferredSSHClient=GnomeTerminal
         com.ibm.iaccess.PreferredSSHClient=Konsole
         com.ibm.iaccess.PreferredSSHClient=Xfce4

Mac examples:
         com.ibm.iaccess.PreferredSSHClient=iTerm2

Windows examples:
         com.ibm.iaccess.PreferredSSHClient=Cygwin
         com.ibm.iaccess.PreferredSSHClient=Putty
         com.ibm.iaccess.PreferredSSHClient=Bash

For cases when the SSH client is not installed to the standard location, you can use the com.ibm.iaccess.PreferredSSHClient property to provide the fully-qualified path to the installed SSH client.

         com.ibm.iaccess.PreferredSSHClient=C:\PuTTY\putty.exe

When the fully-qualified path is provided, you may also need to set com.ibm.iaccess.SSHClientOpt to provide all necessary arguments. For example, to disable warnings if you don't use X11 forwarding:

         com.ibm.iaccess.SSHClientOpts=-x

9.13.1 SSH Terminal Prerequisites

If you receive a connection error within the launched SSH client (for example, "connection refused"), or if a window pops up but immediately vanishes, you may need to start the SSH daemon with the above command.

10.0 Service Diagnostics

If you encounter a problem which requires IBM service, your IBM service representative may direct you to do one or both of the following:

From the main IBM i Access Client Solutions GUI:

• select Tools->Generate Service Logs
  This performs the same function as the command-line option in section 9.1.5 Dump. This function should normally be done immediately after the failure. Depending on the problem, your IBM service representative may direct you to do this multiple times.
• select Tools->Package Service Logs
  This performs the same function as the command-line option in section 9.1.6 Medic. This function gathers details about the workstation environment and packages the service logs in to a .zip file that can be sent to IBM.

11.0 Security

Securing the deployment of IBM i Access Client Solutions (ACS) is something every administrator needs to consider. Since there are a variety of ways to deploy ACS, the items listed here may not be everything needed for your environment. Additional recommendations and considerations will be added periodically.

11.1 Security Best Practices

IBM has identified the items in this subsection to be "Best Practices" and highly recommends they should be followed.

11.1.1 Install Latest Product Version

Always use the latest version of IBM i Access Client Solutions (ACS). IBM provides updates to ACS multiple times a year to add new features, fix problems, and to resolve security issues. Sometimes security issues are identified in Open Source Software (OSS) utilized by ACS. IBM monitors these OSS packages and will provide updated versions regardless of whether or not ACS is vulnerable.

11.1.2 Install Current Java LTS Version

Use a current Long Term Support (LTS) version of Java. The current LTS versions in support are Java 8, Java 11, Java 17, and Java 21. Any of these LTS versions should suffice as long as it is compatible with your TLS/SSL environment.

Security issues found in Java are fixed by the Java provider. You may update your installation of Java independent from updating IBM i Access Client Solutions (ACS) and should do so on a regular basis to make sure you have the latest security updates.

11.1.3 Protecting Product Files

Be aware that when IBM i Access Client Solutions (ACS) ships, the product executables have been signed by IBM. This includes acsbundle.jar and any .dll or .exe. However, signing these files does not prevent someone from replacing them in your deployment with their own hacked version. Security is a shared responsibility between you and IBM. In this case, the security of these files can only be verified from your end by making sure they are signed by IBM before they are used.

11.1.4 Restricting Windows NTLM

IBM recommends not using NT LAN Manager (NTLM).

NTLM has had so many security issues, Microsoft has decided to phase it out sometime in Windows 11 as mentioned here.

NTLM is not used directly by IBM i Access Client Solutions (ACS), nor does ACS have any specific support for it. However, since ACS does not prevent the usage of Universal Naming Convention (UNC) paths, administrators need to be aware that if NTLM is enabled on a workstation, and a hacker is successful at modifying an ACS file where a UNC path can be used, you are vulnerable to a variety of NTLM security issues including the pass-the-hash attack.

For example, ACS is a java application that runs in a Java Virtual Machine (JVM). When a UNC path is encountered, the JVM hands it off to the native platform, in this case Windows. When Windows sees a UNC path, it initiates the authentication to whatever server is specified in the UNC path. If NTLM is enabled, the authentication automatically sends the NTLM hash to the remote server. If the path had been previously modified to point to a server managed by a bad actor, this would allow the NTLM hash to be harvested and used for an additional attack.

If it is not be possible to disable NTLM immediately, the following resources may help:

• NTLM Explained
• Network security: Restrict NTLM: Outgoing NTLM traffic to remote servers
• Network security: Restrict NTLM: Add remote server exceptions for NTLM authentication

11.2 Security Considerations

Since security normally has several different layers, this subsection identifies additional layers of protection you may want to consider.

11.2.1 Restricting Functions

There are several different ways to restrict which ACS functions are available to users. However, these will only restrict access to the ACS function on the user's workstation and do not restrict authority the user has on the IBM i server.

Here are the ways you can select which functions are available:

1. Setting either property com.ibm.iaccess.ExcludeComps or com.ibm.iaccess.IncludeComps in the AcsConfig.properties file allows you to decide which functions are available. See section 9.5 Customized Packages. The installation scripts set com.ibm.iaccess.ExcludeComps in AcsConfig.properties based on responses provided by the user while running the script.

   Note: If the user has write access to AcsConfig.properties, they could modify which functions are available. Or if they deploy their own copy of IBM i Access Client Solutions (ACS), they could select for themselves which functions are available.

2. An administrator can restrict which features are available independent of settings in AcsConfig.properties. See the RESTRICT plugin in section 9.1.26 RESTRICT. This feature is also available from the main GUI when IBM i Access Client Solutions (ACS) is started as an Administrator. Start ACS as an Administrator (or root authority using the sudo command on Mac and Linux). Then from Edit->Preferences a Restrictions tab will now be available. On Windows, restrictions set in this way can also be exported to a .reg file and propagated to other users.

   Note: IBM does not recommend using this option in combination with setting com.ibm.iaccess.ExcludeComps or com.ibm.iaccess.IncludeComps.

3. Functions may also be restricted from the IBM i side using the WRKFCNUSG command. The same settings used for IBM i Access for Windows are supported by IBM i Access Client Solutions (ACS). These settings can also be adjusted from IBM Navigator for i.

For additional information on this topic, see the IBM support document Restrict Functions in Access Client Solutions

11.2.2 Restricting Files

Restricting file permissions is a good general practice. For example, if using a server deployment for multiple users, you should:

• restrict AcsConfig.properties to be read only.
• consider restricting the executable product files to be read/execute.

11.2.3 TLS/SSL Certificate Store

When using IBM i Access Client Solutions (ACS) with TLS/SSL, by default, a user will get prompted to accept a Certificate Authority that is not already in their certificate store. Each user has their own certificate store. Its location is on the Key Management panel: Select Tools->Key Management from the ACS main menu.

To avoid user confusion and potential security issues with users having to accept a Certificate Authority, you can use any combination of the following options:

1. Populate the certificate store ahead of time so the user will not get prompted.
2. Set a common location for all users to share the same certificate store by setting the property com.ibm.iaccess.CertFile in AcsConfig.properties.
   For example: com.ibm.iaccess.CertFile=/Users/Public/Documents/IBM/Security/cacerts
   See AcsConfig.properties for special keywords that can be used when setting this property.
3. Prevent users from getting prompted to accept a certificate authority by setting the property com.ibm.iaccess.DisableCertificateAuthorityPrompt=true in the AcsConfig.properties file.

11.2.4 TLS/SSL Certificate Store for Windows Application Package

To make certificate authorities available to the optional Windows Application Package, use the KeyManagement tool:

1. Select Tools->Key Management from the ACS main menu.
2. Select the certificate authorities you would like to make available.
3. Hit the Push to Windows... button.

Appendix A - Frequently Asked Questions (FAQ)

Q1    When I try to start IBM i Access Client Solutions I get the following
      error:
             class cannot be loaded: java.lang.UnsupportedClassVersionError
A1-1  You need to use JDK 8.0 or higher.  See section 3.0 Prerequisites

Q2    When I try to start the product using one of the provided binary files or
      scripts from a shell or terminal session, I get the following error:
         Permission denied
A2-1  Check the file permissions of the file to make sure you have execute
      permission.   See section 6.0 File Permissions.

Q3    When I double-click on one of the provided files to start the product,
      nothing happens.
A3-1  Java may not be installed.   See section 3.0 Prerequisites
A3-2  The file you are using to start the product may not have execute
      permission.  See section 6.0 File Permissions.
A3-3  There may be problems with your environment.  To see what errors may be
      occurring, try running the provided file from a command line.
      See section 7.3 Starting the Product (using the command-line).

Q4    I want to use one of the binary files to start the product, but I get the
      following error:  "Error loading Java module."
A4-1  The binary was unable to locate the home directory of the java
      installation.
      Please verify java is installed.   See section 3.0 Prerequisites.
A4-2  Section 7.1.1 Starting the Product - Additional Options
      contains additional methods for starting the product using a binary file.

Q5    After I set the JAVA_HOME environment variable, the binary file I use to
      start the product works from a command-line, but does not work when I
      double-click the file.
A5-1  The JAVA_HOME environment variable may not be visible from the file manager
      you are using when you double-click the file.  Setting environment
      variables varies across operating systems and so does their visibility.
      Try setting the JAVA_HOME environment variable as a system environment
      variable for your operating system.  Your operating system may refer to
      system environment variables as global environment variables.
      After setting the JAVA_HOME environment variable, close and reopen your
      file manager and try to double-click the binary file again.

Q6    When I double-click on one of the provided files to start the product, a
      text editor displays the file.
A6-1  Make sure you are using a script that has a file extension your operating
      system recognizes.
A6-2  Try one of the other scripts.
A6-3  Change the program that opens the file.
A6-4  Check the file permissions of the file to make sure you have execute
      permission.   See section6.0 File Permissions.

Q7    When I double-click on one of the provided files to start the product, I am
      prompted for which program should be used to open the file.
A7-1  Make sure you are using a script that has a file extension your operating
      system recognizes.
A7-2  Set the program that opens the file to something compatible with the binary
      file or script you are using.  For example, Terminal (on Mac).
A7-3  Check the file permissions of the file to make sure you have execute
      permission.   See section6.0 File Permissions.

Q8    When I start IBM i Access Client Solutions on a Mac from Finder, a
      terminal session pops up and does not go away even after ending
      IBM i Access Client Solutions.
A8-1  To eliminate the terminal session from popping up, use the install scripts
      for Mac in the QuickStartGuide.

Q9    What is the best way to start the product?
A9-1  You may start the product with any of the three methods in section
      7.0 Starting the Product using either the binaries, scripts, or the
      command-line.  Any method that works in your environment is acceptable.

Q10   Why are there both binary files (Start_Programs) and scripts
      (Sample_Scripts) for starting the product?
A10-1 The scripts are not operating system specific and provide a more generic
      way to start the product when the platform specific binary file does not work.
A10-2 Some operating systems require binaries when defining file associations.
      For most cases, the binary files should be used to start the product.
A10-3 Some environments may have firewalls that restrict access to portions of
      IBM i Access Client Solutions.  Using one of the binary files to start the
      product will make it easier for system administrators to authorize access.

Q11   After installing JDK 8.0 (or higher), I am still getting the following
      error:
      class cannot be loaded: java.lang.UnsupportedClassVersionError
A11-1 The default version of java being used on your workstation is prior to
      JDK 8.0.  You will need to use an option that explicitly specifies the
      path to the Java home for JDK 8.  See section 7.1.2 Finding the Java
      Home Path.  Use the Java home path for one of the methods described in
      either of the following sections:
      7.1.1 Starting the Product - Additional Options

      7.3 Starting the Product (using the command-line)


Q12   I am not able to import customized keyboard mapping files (.kmp) from
      my Windows 5250 emulator sessions.
A12-1 In the initial version of IBM i Access Client Solutions which became
      available in July 2012, importing .kmp files from Windows 5250 emulator
      session profiles (.ws) was not supported.  As of the version which
      became available in October 2012, importing .kmp files from 5250
      session profiles (.ws) is now supported.

Q13   Keyboard customization for the 5250 emulator is a lot different than it
      was on Windows.  Do you have any suggestions?
A13-1 Keyboard mapping is divided into categories.  From an emulator session:
      Click Edit > Preference > Keyboard, or click the Remap button on the
         toolbar.
      Click the Key Assignment tab.
      Select a Category.  Default key mappings will appear under the
         "Host Functions" and the "Menu Commands" categories.
      Select the function you want to assign.
      Click Assign a Key.
      On your keyboard, press the key (or key combination) you want to assign
         to this function.
A13-2 For help on custom key mappings:
      Click Edit > Preference > Keyboard, or click the Remap button on the
      toolbar.  Select the Help button.

Q14   When I try to start the product on Mac OS X 10.8 Mountain Lion, I get
      a pop up message indicating the application is not signed.
A14-1 This is a security policy enforced by default beginning with Mac OS X
      10.8 Mountain Lion. See the following web page for how to enable the
      application to run:
      http://macperformanceguide.com/MountainLion-application-signing.html

Q15   I am a user of IBM i Access for Windows, can I migrate my system
      configurations to IBM i Access Client Solutions?
A15-1 See section9.6.1 Migrating System Configurations.

Q16   I am a user of IBM i Access for Windows, can I migrate my emulation
      profiles to IBM i Access Client Solutions?
A16-1 See section 9.6.2 Migrating 5250 Emulation

Q17   I am a user of IBM i Access for Windows, can I migrate my Data Transfer
      request files to IBM i Access Client Solutions?
A17-1 See section9.6.3 Migrating Saved Data Transfer Request Files.

Q18   Does EHLLAPI work with IBM i Access Client Solutions?
A18-1 See section 9.6.4 EHLLAPI

Q19   Does kerberos work with IBM i Access Client Solutions?
A19-1 See section 9.6.5 Kerberos

Q20   I am a system administrator and would like to hide certain functions
      from my users.
A20-1 See section 9.5 Customized Packages

Q21   When I select a help icon on a panel, no text is displayed.
A21-1 The help text is normally displayed in the desktop browser.  In some cases,
      the desktop may not have a browser or it may not be configured correctly.
A21-2 To display the help text without using the desktop browser, set the
      following property in the AcsConfig.properties file:
         com.ibm.iaccess.javaAwtDesktopAllowed=false
      Alternatively, the property may be set from from the command line like
      other java properties as follows:
         -Dcom.ibm.iaccess.javaAwtDesktopAllowed=false

Q22   When using Data Transfer, I select an Output device of either "Active Excel
      Spreadsheet" or "Active Calc Spreadsheet" and I get the following error:
         "Active Spreadsheet was not found"
Q22-1 There is no active spreadsheet.  Open either a new or existing spreadsheet
      and try the request again.
Q22-2 There may be a bitness mismatch between the spreadsheet application you are
      using and the Java Virtual machine running IBM i Access Client Solutions.
      See section 9.8 Data Transfer Support for Excel and Calc Spreadsheets

Q23   When using Data Transfer on a Mac, I do not see any options in Output
      device for interacting with an active spreadsheet.
Q23-1 Data Transfer is not able to interact with active spreadsheets on Mac due
      to the bitness mismatch between the OpenOffice application and the JVM
      running IBM i Access Client Solutions.  For additional details, see section
      9.8 Data Transfer Support for Excel and Calc Spreadsheets.

Q24   When using Data Transfer, I select an Output device of "Active Calc
      Spreadsheet" and nothing appears in the Name box.
Q24-1 This is normal for new Calc spreadsheets that have never been saved.
      DataTransfer will still be able to update the spreadsheet with downloaded
      data.

Appendix B - Update History

See the following web page:
IBM i Access Client Solutions (5733XJ1)