Introduction

Installation, updates, upgrades, patching and uninstallation are performed by use of the YADE Installation Script. The script makes use of the .tar.gz/.zip archives provided for initial installation of newer releases.

JS7 - Installation instructions apply.
For environments with a larger number of YADE instances the installation, update, upgrade, patch and uninstallation processes can be automated in a number of ways:
- Users can apply the YADE Installation Script that is described in this article.
- Users can automate packaging and deployment of YADE, see JS7 - Deployment.
- Users can apply the YADE Installation Script with their preferred tools such as Ansible®, Puppet®, Chef®.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.0

Security

Secure rollout of JS7 products is critical. It is therefore recommended that the solution described here is adjusted to suit specific security needs.

Rollout of JS7 YADE is considered critical as the software allows file transfers to be executed for a larger number of servers.
- Integrity of the sources for downloads of JS7 products deserves attention.
- This includes intermediate devices to which JS7 software installers are stored in a user's environment.
- It is an option to run the YADE Installation Script from sudo and to use the digest functionality that compares the script to a hash value stored with the sudoers file.
The solution provided for updating, upgrading and patching YADE is based on shell scripting by design:
- to provide readability and to rely on OS commands only,
- to deny the use of any 3rd-party components and additional dependencies that require code to be executed on the machines that run YADE.
The YADE Installation Script can be integrated in a number of ways:
- by running one's own SSH scripts on top of the YADE Installation Script,
- by use with tools such as Ansible®, Puppet® that make use of an SSH Client,

YADE Installation Script

The YADE Installation Script is provided for download and can be used to automate updates, upgrades and patches of YADE.

The script is available for Linux, MacOS®, AIX®, Solaris® using bash, dash, ksh and zsh POSIX-compatible shells. For AIX®, Solaris® automated installation is supported, automated configuration is not.
The script can be used to install, update or patch YADE using the installation options.
The script terminates with exit code 0 to signal success, with exit code 1 for command line argument errors and with exit code 2 for non-recoverable errors.
The script is intended as a baseline example for customization by JS7 users and by SOS within the scope of professional services.
See the information in the JS7 - YADE Command Line Operation article.

Download

Find the YADE Installation Script for download from JS7 - Download.

Usage

Invoking the YADE Installation Script without arguments displays the usage clause:

YADE Installer Script: js7_install_yade.sh

Usage: js7_install_yade.sh [Options] [Switches]

  Installation Options:
    --home=<directory>                 | required: directory to which the YADE will be installed
    --data=<directory>                 | optional: directory for YADE data files, default: <home>/var
    --logs=<directory>                 | optional: directory to which the YADE writes log files, default: <data>/logs
    --home-owner=<account[:group]>     | optional: account and optionally group owning the home directory, requires root or sudo permissions
    --data-owner=<account[:group]>     | optional: account and optionally group owning the data directory, requires root or sudo permissions
    --release=<release-number>         | optional: release number such as 2.8.0 for download if --tarball is not used
    --tarball=<tar-gz-archive>         | optional: the path to a .tar.gz archive that holds the YADE installation or patch tarball
                                       |           if not specified the YADE tarball will be downloaded from the SOS web site
    --patch=<issue-key>                | optional: identifies a patch from a Change Management issue key
    --patch-jar=<jar-file>             | optional: the path to a .jar file that holds the patch
    --backup-dir=<directory>           | optional: backup directory for existing YADE home directory
    --log-dir=<directory>              | optional: log directory for log output of this script
    --return-values=<file>             | optional: path to a file that holds return values such as the path to a log file

  Switches:
    -h | --help                         | displays usage
    --force-sudo                        | forces use of sudo for operations on directories
    --uninstall                         | uninstalls YADE and removes <home> and <data> directories
    --uninstall-home                    | uninstalls YADE and removes <home> directory only
    --uninstall-data                    | uninstalls YADE and removes <data> directory only
    --show-logs                         | shows log output of the script
    --make-dirs                         | creates the specified directories if they do not exist
    --move-libs                         | moves an existing YADE's lib directory instead of removing the directory

Installation Options

--home
- Specifies the directory in which the YADEshould be installed.
--data
- Specifies the directory in which YADE data such as configuration files should be stored.
- By default the <home>/var directory is used, see--home option.
--logs
- Specifies the directory to which the YADE stores log files.
- By default the <data>/logs directory is used, see option --data.
--home-owner
- Optionally specifies the user account and group that should own the home directory. By default the home directory is created and owned by the current user account.
- Syntactically a user account and optionally a group can be specified, for example --home-owner=sos or --home-owner=sos:sos. If the group is not specified then a group with the name of the user account is assumed.
- Use of this option requires sudo permissions for the user account that runs the YADE Installation Script.
--data-owner
- Optionally specifies the user account and group that should own the data directory. By default the data directory is created and owned by the current user account.
- Syntactically a user account and optionally a group can be specified, for example --data-owner=sos or --data-owner=sos:sos. If the group is not specified then a group with the name of the user account is assumed.
- Use of this option requires sudo permissions for the user account that runs the YADE Installation Script.
--release
- Specifies a release number such as 2.3.1 for download from the SOS web site if the --tarball option is not used.
--tarball
- Optionally specifies the path to a .tar.gz file that holds the YADE installation or patch files. If this option is not used, then the installation or patch tarball will be downloaded from the SOS web site for the release indicated with the --release option.
- Download is performed with curl that considers http_proxy and https_proxy environment variables and respective settings from a .curlrc file.
--patch
- A patch is identified by an issue key in the Change Management System, for example YADE-1984.
- Patches are downloaded from the SOS web site if the --tarball option is not used.
- Patches are added to the YADE's <home>/lib/patches directory. Note that the patches sub-directory will be emptied when updating a YADE installation later on.
- If a backup directory is specified then YADE's existing installation directory will be added to a .tar.gz backup file in this directory.
--patch-jar
- Optionally specifies the path to a .jar file that holds the patch if a patch is provided in this format.
--backup-dir
- If a backup directory is specified then YADE's existing installation directory will be added to a .tar.gz file in this directory before applying changes to the YADE installation.
- File names are created according to the pattern: backup_js7_yade.<hostname>.<release>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.tar.gz
  - For example: backup_js7_yade.centostest_primary.2.8.0.2025-05-19T20-50-45.tar.gz
- A backup is intended to restore files in the YADE's installation directory, not in its data directory, see --data. The purpose of a backup is to restore files that are replaced by the YADE Installation Script. No backup will be taken if one of the --uninstall options is used.
--log-dir
- If a log directory is specified then the YADE Installation Script will write information about processing steps to a log file in this directory.
- File names are created according to the pattern: install_js7_yade.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
- For example: install_js7_yade.centostest_primary.2025-05-19T20-50-45.log
--return-values
- Optionally specifies the path to a file to which return values will be added in the format <name>=<key>. For example:
  - log_file=install_js7_yade.centostest_primary.2025-05-20T04-54-31.log
  - backup_file=backup_js7_yade.centostest_primary.2.8.0.2025-05-20T04-54-31.tar.gz
- An existing file will be overwritten. It is recommended to use a unique file name such as /tmp/return.$$.$RANDOM.properties.
- A value from the file can be retrieved like this:
  - backup=$(cat /tmp/return.$$.$RANDOM.properties | grep "backup_file" | cut -d'=' -f2)

Switches

-h | --help
- Displays usage.
--force-sudo
- Specifies that sudo is used when performing operations on directories. This switch is required if the home or data directory is not owned by the user account running the YADE Installation Script.
--uninstall
- Uninstalls the YADE by removing the <home> and <data> directories.
--uninstall-home
- Uninstalls the YADE by removes the <home> directory only.
--uninstall-data
- Uninstalls the YADE and preserves the <home> directory.
--show-logs
- Displays the log output created by the script if the --log-dir option is used.
--make-dirs
- If directories are missing that are indicated with the --home, --backup-dir or --log-dir options then they will be created.
--move-libs
- For an existing YADE installation the lib sub-directory includes .jar files that carry the release number in their file names. If replaced by a newer version the lib directory has to be moved or removed. This switch tries to move the directory to a previous version number as indicated from the .version file in the YADE's home directory, for example to rename lib to lib.2.8.1.
- Files in the lib/user_lib sub-directory are preserved.

Exit Codes

1: argument errors
2: non-recoverable errors
4: this exit code is returned if no --tarball option is used and download of the tarball reports errors

Examples

The following examples illustrate typical use cases. Users should consider to specify current releases, see JS7 - Download.