New Unix installation

Before commencing a new Unix installation, confirm that the following system requirements for EMu 8.0 are met:

Note: In the following steps, the term ~emu refers to user emu's home directory, typically /home/emu. For the most part you only need to key in ~emu; however, note that in some instances you are requested to key in the expanded home directory; this could be /home/emu but should be confirmed.

EMu is installed on a Unix machine as a server application. In order to restrict access to the database files, a Unix group is created.

EMu requires a user and group account to be set up. The user account is called emu and it is used to administer EMu. The group account, emuadmin, is used to limit access to EMu data files.

First we add user emu, group emuadmin and create the emu home directory:

  1. Log in as root
  2. Launch the User Account Management software for your host.
  3. Create a new group called emuadmin.
  4. Create a new user called emu with a default group of emuadmin:
    • Ensure that the last component of user emu's home directory is emu, e.g. /home/emu.

    • Login shell in order of preference is: bash, ksh, sh.

  5. The permissions for user emu's home directory must provide a normal user with read and execute access:
    1. Enter cd ~emu
    2. Enter chmod 755 .

Texpress is the object oriented database engine used by EMu for data management. It provides extremely high speed retrieval, while providing flexible data structures which simplify the overall data module employed by EMu.

In this step we install both Texpress (the database engine), and the Applications Programming Interface to Texpress, TexAPI.

Note: The following instructions describe how to set up Texpress for use with EMu. They do not detail a full installation of Texpress on Unix. Please see the Texpress documentation for instructions on performing a complete installation of Texpress.

Note: In the following steps, xxx is the version of Texpress being installed (typically the current version). If installing Texpress version 10.0.001 for instance, you'd replace xxx with 001 in the following command: mkdir -p texpress/10.0.xxx/install. You can check which is the latest version here (you will download it in Step 5).

  1. Log in as emu
  2. Enter cd ~emu
  3. Enter mkdir -p texpress/10.0.xxx/install
  4. Enter cd texpress/10.0.xxx/install
  5. Download the appropriate Texpress version for your Unix machine and save it to:

    ~emu/texpress/10.0.xxx/install

    and name it texpress.sh.

  6. To extract the release, enter:

    sh texpress.sh

  7. Enter . ./.profile
  8. Enter export TEXGROUP=emuadmin
  9. To commence the installation script, enter:

    bin/texinstall ~emu/texpress/10.0.xxx

    Note: Replace ~emu with user emu's expanded home directory, typically /home/emu.

  10. Enter cd ~emu/texpress/10.0.xxx
  11. Enter . ./.profile
  12. Enter texbldperms
  13. Enter bin/texlicinfo

    Obtain your Texpress licence code and save it in a file called .licence.

  14. To install the licence, enter:

    bin/texlicset < .licence

  15. Enter \rm -fr install
  16. Enter cd ~emu/texpress
  17. Enter ln -s 10.0.xxx 10.0

Stay logged in as emu for the TexAPI installation.

Note: In the following steps, xxx is the version of TexAPI being installed (typically the current version). If installing TexAPI version 6.0.012 for instance, you'd replace xxx with 012 in the following command: mkdir 6.0.xxx. You can check which is the latest version here (you will download it in Step 3).

The following steps assume you are logged in as emu:

  1. Enter cd ~emu/texpress
  2. Enter mkdir 6.0.xxx
  3. Download the appropriate TexAPI version for your Unix machine and save it to:

    ~emu/texpress

    and name it texapi.sh.

  4. Enter sh texapi.sh -i ~emu/texpress/6.0.xxx

    Note: Replace ~emu with user emu's expanded home directory, typically /home/emu.

  5. Enter \rm -f texapi
  6. Enter ln -s 6.0.xxx texapi
  7. Enter \rm -f texapi.sh
  8. To close the command shell, enter exit
  9. Log out.

PAM allows user name and password checking to be performed by 3rd party authentication mechanisms. These mechanisms include:

  • LDAP
  • Radius
  • Unix (standard password lookup)

Texpress 8.0 introduced support for PAM as the mechanism used to authenticate users when they log in to EMu. The following operating system releases support PAM:

  • Solaris (SPARC)
  • Solaris (x86)
  • FreeBSD
  • Linux

The standard PAM configuration for all versions of Unix except for Red Hat or SUSE Linux defaults to using the standard Unix password mechanism for user authentication. In the case of Red Hat or SUSE Linux, the user authentication will fail unless a suitable PAM configuration is installed. Thus for all versions of Unix except Red Hat or SUSE Linux it is not necessary to configure PAM if you want to use the standard Unix password authentication. If you want to use either LDAP or Radius servers, then you will need to install a suitable PAM configuration.

PAM configuration may be set up in one of two ways:

  • with a single configuration file (/etc/pam.conf). This method is used by Solaris.

    Solaris does not require any PAM configuration if the standard Unix authentication mechanism (password file) is to be used. If you want to alter the standard configuration to use, say, LDAP then:

    1. Log in as root
    2. Enter vi /etc/pam.conf
    3. Add the following lines to the top of the configuration file:

      texpress

      auth

      sufficient

      authentication module

      texpress

      account

      sufficient

      authentication module

      texpress

      passwd

      sufficient

      authentication module

    4. Save the changes and exit the file.

    It may be necessary to alter the file /etc/nsswitch.conf to include support for certain authentication methods (e.g. LDAP). For information about what modules are supported, consult your operating system manual or view the EMu Password Management documentation for more details.

  • with a directory (/etc/pam.d) where individual files configure services. All variants of Linux and FreeBSD use this method.

    In order for EMu to authenticate users on Linux, it is necessary to add a PAM configuration file for service texpress. The configuration should be stored in the file /etc/pam.d/texpress.

    Tip: FreeBSD also uses this mechanism but does not require configuration by default.

    To set up PAM:

    1. Log in as root
    2. Enter vi /etc/pam.d/texpress
    3. Enter the following text into the file:
      Red Hat 6, CentOS 6 or Fedor Core 8 Linux
      #
      #  /etc/pam.d/texpress
      #
      auth      include   system-auth
      account   include   system-auth
      password  include   system-auth
      session   include   system-auth
       
      Red Hat 5 or Centos 5 Linux
      #
      # /etc/pam.d/texpress
      #
      auth     required /lib/security/pam_stack.so service=system-auth
      account  required /lib/security/pam_stack.so service=system-auth
      session  required /lib/security/pam_stack.so service=system-auth
      password required /lib/security/pam_stack.so service=system-auth
       
      SUSE Linux
      #
      # /etc/pam.d/texpress
      #
      auth     required pam_unix2.so
      account  required pam_unix2.so
      session  required pam_unix2.so
      password required pam_unix2.so
       
      Ubuntu
      #
      # /etc/pam.d/texpress
      #
      @include common-auth
      @include common-account
      @include common-session
      @include common-password

    4. Save the changes and exit the file.

    If another authentication mechanism is required, it is necessary to alter the module loaded. Please consult your operating system manual or view the EMu Password Management documentation for more details.

Use another authentication mechanism

If you want to use another authentication mechanism, it is necessary to alter the PAM configuration for service texpress to indicate what method is required. PAM support in Texpress requires three services to be configured:

  • auth - authenticate the user name and password.
  • account - check if user account is valid or whether password has expired.
  • passwd - provide services for users to change passwords.

EMu is designed to allow multiple installations to coexist. Each installation is placed in a directory within user emu's home directory. The name of this directory typically reflects the client system being installed. The client name may be any name, thus allowing test and production environments to be set up for the same system. In the steps below clientname refers to the name of the client directory for the current installation.

  1. Log in as emu
  2. Enter cd ~emu
  3. The install bundle must be unarchived into a new temporary directory. It is recommended that this directory is named ~emu/clientname/install

    Enter mkdir -p clientname/install

  4. Enter cd clientname/install
  5. Download the appropriate EMu server version bundle and save it to ~emu/clientname/install.
  6. To extract the client release, enter:

    sh emu-clientname-yymmddv.sh

    Note: Be sure to replace emu-clientname-yymmddv.sh with the name of the actual release file.

  7. Enter . ./.profile
  8. To commence the installation script, enter:

    bin/emuinstall clientname

  9. Enter cd ~emu/clientname
  10. Enter cp .profile.parent ../.profile
  11. Enter cd ..
  12. Enter vi .profile-local
  13. Add a single line client clientname to the file and save it.

    Note: If a default client is already registered, you may leave the existing value.

  14. Enter . ./.profile
  15. Enter client clientname
  16. Enter cd etc
  17. View the config.sample file. If you wish to alter some of these settings to suit the client, then:
    1. Enter cp config.sample config
    2. Enter vi config
    3. Edit as appropriate, then save the file.

    Note: Be sure to set EMUSMTPSERVER to the hostname of your mail server machine.

  18. Enter cd ..
  19. Enter emubldlinks
  20. Enter emulutsrebuild -t -f
  21. Removal of the temporary install directory (and its contents) is recommended. Enter:

    \rm -fr install

  22. In order to allow easier upgrades of Texpress (without having to update the etc/opts file) all Texpress options are now set in the client specific .profile-local file. When installing EMu 8.0 you will have to add all Texpress options required for the installation. In particular the dateorder, dateformat, timeformat, latitudeformat, longitudeformat, tmppath and loadmemory)settings should be examined.

    Tip: See Texpress options for a list of acceptable values.

    If necessary, modify the Texpress options:

    1. Enter vi .profile-local and modify the Texpress options as required.

      An example file is:

      TEXPRESSOPTS="${TEXPRESSOPTS} dateorder=mdy dateformat='dd MMM yyyy'" export TEXPRESSOPTS

      NOTE: the value of the Date Input Registry entry and dateorder option must be the same; if the Date Input Registry entry is set to MDY, dateorder must be mdy.

    2. Save the .profile-local file.

    3. Enter client clientname

    Any other client specific setting can be set at this time (e.g. shell specific settings, etc.).

  1. Enter cd etc
  2. If the IMu server is to be used, the following steps are required:
    1. Enter cp imuserver.conf.sample imuserver.conf
    2. Enter vi imuserver.conf
    3. Edit as appropriate, then save the file.

    Be careful to set the main-port property as a minimum. The value of main-port is generally 20000 more than that used by the Windows client.

    -OR-

    If the IMu server is not to be used, the following steps are required:

    1. Enter cd ..
    2. Enter touch loads/imu/disabled
  3. To close the command shell, enter exit
  4. Log out.

You should also add client specific services. To determine the port required, consult the EMu Ports documentation (Axiell staff only).

  1. Log in as root

    Note: In all examples below ~emu must be expanded to emu's home directory, which is typically /home/emu.

  2. Enter vi /etc/services
  3. Add new services to the end of the file and save the file.

    emu

    20000/tcp

    emutrain

    20001/tcp

    emutest

    20002/tcp

    Add any client specific services (consult the EMu Ports documentation to determine the port required), e.g.:

    emuclientnameport/tcp (replace port with port number)
  4. Save the file.
  5. Select one of the following installation setups:

Note: If the institution has implemented a Power Save policy, see the EMu Help for possible workarounds for the Cannot receive from remote host (number 309) error message. This involves editing or removing -t60 in the configuration below.

If your system uses inetd to start up system services, the following setup is required. All versions of Unix use inetd by default except for Red Hat Linux 7.0 or later and Solaris 10 or later. If the file /etc/inetd.conf exists, these steps are required:

  1. Enter vi /etc/inetd.conf
  2. Add the following line to the end of the file:

    emuclientname stream tcp nowait root ~emu/clientname/bin/emurun emurun texserver -aemu -i -L -t60

    If you also want the emu service to connect to your emuclientname, add the line:

    emu stream tcp nowait root ~emu/clientname/bin/emurun emurun texserver -aemu -i -L -t60

  3. Save the file.
  4. You will need to restart inetd for the changes to take effect. Locate the process id number pid for the inetd process and then:

    Enter kill -HUP pid

-OR-

If installing on a Linux system or the file /etc/xinetd.conf exists, the following steps are required:

  1. Enter cd /etc/xinetd.d
  2. Enter vi emuclientname
  3. Enter the following text in the file:
    # default: on
    service emuclientname
    {
    flags = REUSE
    protocol = tcp
    socket_type = stream
    wait = no
    user = root
    server = ~emu/clientname/bin/emurun
    server_args = texserver -aemu -i -L -t60
    log_on_failure += USERID
    disable = no
    }
  4. Save the file.
  5. You will need to restart xinetd for the changes to take effect. Locate the process id number pid for the xinetd process and then:

    Enter kill -HUP pid

Note: On some versions of Red Hat it may be necessary to enter kill -USR2 pid> or /etc/init.d/xinetd restart> in order to update xinetd. To determine what signal is required on Red Hat, consult the manual entry for xinetd.

-OR-

If installing on a Solaris system, version 10 or later using smf (Service Management Facility), the following steps are required:

  1. Enter vi /tmp/inetd
  2. Add the following line to the file:

    emuclientname stream tcp nowait root ~emu/clientname/bin/emurun emurun texserver -aemu -i -L -t60

    If you also want the emu service to connect to your emuclientname, add the line:

    emu stream tcp nowait root ~emu/clientname/bin/emurun emurun texserver -aemu -i -L -t60

  3. Save the file.
  4. Enter inetconv -f -i /tmp/inetd
  5. To determine if the services are enabled, use the inetadm command.
  1. Locate the name of the local system initialization file for your operating system. Some examples are:

    Operating System

    File

    FreeBSD

    /etc/rc.local

    Red Hat/CentOS Linux

    /etc/rc.d/rc.local

    Solaris

    /etc/rc3.d/S99emu

    SUSE Linux

    /etc/rc.d/rc3.d/S99emu

  2. Enter vi file where file is the name of the local system initialization file.
  3. Add the following lines to the end of the file:
    #
    # EMu startup
    #
    ~emu/clientname/bin/emuboot
  4. Save the file.
  5. Enter ~emu/clientname/bin/emuboot
  6. Log out.

Significant speed improvements in the EMu auditing facility may be achieved by installing two perl packages:

XML::Parser::Expat and File::FcntlLock

The installation of these packages is optional but recommended.

EMu uses the Image::Magick and Image::ExifTool perl packages for image processing and manipulation. The installation of these package is required.

  1. Log in as root
  2. Enter perl -MCPAN -e shell
  3. Enter install XML::Parser::Expat
  4. Enter install File::FcntlLock
  5. Enter install Image::Magick
  6. Enter install Image::ExifTool
  7. Enter quit
  8. Log in as emu
  9. Enter emuload stop audit
  10. Enter emuload start audit

The EMu client runs on Windows 7, 8, 8.1 and 10.

The EMu licensing model permits the EMu client to be installed on an unlimited number of PCs.

If an older EMu client is currently installed on the PC, it is recommended that the old EMu client is removed before installing the new one.

  1. Log in as a user with Administrator privileges.
  2. Select Settings>Control Panel from the Start menu to display the Control Panel.
  3. Select Add/Remove Programs and from the pull down menus choose File>Open.

    The Add/Remove Program Properties dialogue displays.

  4. On the Install/Uninstall tab, select KE EMu and then click Add/Remove.

    The Uninstall program will commence.

  5. Follow the prompts to remove EMu.

    You may be prompted to confirm the removal of various system files (typically files ending in .dll). If unsure whether it is safe to remove a system file, click No. It is safe to confirm the removal of any file under the EMu installation directory (typically C:\Program Files\KESoftware\EMu).

  6. Click OK to close the dialogue.
  7. Select File>Close to close the Control Panel.

Tip: Details about automating EMu client installations (an unattended install) can be found here.

  1. Log in as a user with Administrator privileges.
  2. From the EMu Release site:
    1. Locate the client release you require, right-click its hyperlink and select Save Target As... (or similar).
    2. Browse to a temporary directory (e.g. C:\WINDOWS\TEMP) and save the file.
  3. Select Run... from the Start menu.

    The Run dialogue displays.

  4. Click Browse... to display the Browse dialogue and locate the client release you downloaded.
  5. Select the file and click Open.
  6. Click OK.

    The EMu client installation program will run and the Welcome dialogue will display.

  7. Click Next.

    The Licence Agreement dialogue displays.

  8. Read the licence and click Yes if you accept the terms and conditions.

    The Choose Destination Location dialogue displays.

    If you intend to perform a Network Server installation (see below), browse to the appropriate network drive and folder

    -OR-

    For Network Client and Standalone installations (see below) the default location is recommended.

  9. Choose the destination location and click Next.

    The Select Components dialogue displays:

    • A Network Server/Network Client installation will allow sharing of most EMu client files. The Network Server must first be installed on a network drive. Each PC should then have the Network Client installed and, when asked, reference the previously installed Network Server. Subsequent installations of EMu need only update the Network Server component. This is the recommended style of set-up for medium to large institutions.

    -OR-

    • If your PC does not have access to a suitable network file server, perform a Standalone installation. For this style of installation a subsequent EMu client upgrade will require the client to be re-installed on the PC.

  10. Select the required option and click Next.
  11. Network Client only: the Select EMu Network Server Folder dialogue will display.
    1. Click Browse.

      The Select Network Folder dialogue will display.

      1. Browse to the network drive and folder and then click OK.
      2. Click Next.

    The Start Installation dialogue will display.

  12. Click Next to install the EMu Client.

    The Installing dialogue will appear indicating how far the installation has proceeded.

    After the installation has finished, the Installation Complete dialogue will display.

  13. Click Finish.

Support has been added to EMu for the display of PDF images. In order to enable this functionality in EMu it is necessary to install the open source tool GhostScript. If GhostScript has not already been installed:

  1. Download the installation file (21.57 MB) from the EMu website.
  2. Run the executable.