Teamwork Cloud 18.5 SP3 Documentation
- Created by Daiva Vaisnoriene, last modified by Jaturavit Suwanyingjarern on Dec 22, 2020
This page shows the example to install and configure Teamwork Cloud (TWCloud) 18.5 Standard Edition on Centos 7.x, deployed on a single server. It also shows the configuration in which both the Teamwork Cloud node as well as the underlying Cassandra node are installed on the same server.
TWCloud installation and configuration on Centos 7.x on a single server.
Minimum server system requirements:
- 8 Processor Cores - i.e. Quad Core Hyper-threaded CPU (such as Intel E3-1230 or faster).
- 32 GB RAM (Motherboard with an ECC RAM is always preferred on any critical database server).
- Linux (RedHat/CentOS 7), 64 bit. Scripts need to be modified slightly for Centos 6.6 - 6.9 due to different system daemon and firewall configuration.
Please read the article for additional server recommendations for capacity and performance from the following link:
https://docs.datastax.com/en/cassandra/2.2/cassandra/planning/planPlanningHardware.html
If you use SATA drives and not SSD's, we recommend using a caching controller with BBU, configured for write back. In this configuration (single node Cassandra), we recommend using RAID - the aforementioned link is referring to multi-node Cassandra deployments where native Cassandra replication is in place, which is not the case in this single node instance.
In order to install a full working environment, the following is required:
- Oracle Java (Java Hotspot) 1.8.0_152
- A FlexNet License Server
- Cassandra 2.2.8
- Teamwork Cloud
Preparing the operating system
Partitioning the drives
In order to achieve adequate performance, separate partitions must be created, ideally on separate drives, to avoid i/o contention. We recommend 3 separate block devices (disks). The first block device will contain the operating system as well as a mount for the programs (/opt/local). The second block device (preferably SSD) will contain a mount point at /data - this is the device which must have high storage capacity for all of the data. The third block device will contain a mount point at /logs - this device should preferably be SSD, but does not need to be of high capacity, since it will only store the commit logs, which are by default limited to 8GB (if using SSD, this can be a partition on the same block device as the data partition). All partitions should be formatted using the XFS file system, and there must not be a swap partition.
The following is an example of the contents of /etc/fstab after partitioning, where the partitions were created using LVM:
# # /etc/fstab # Created by anaconda on Tue May 2 16:31:05 2017 # # Accessible filesystems, by reference, are maintained under '/dev/disk' # See man pages fstab(5), findfs(8), mount(8) and/or blkid(8) for more info # /dev/mapper/cl_twccentos7-root / xfs defaults 0 0 /dev/mapper/cl_twccentos7-data /data xfs defaults 0 0 /dev/mapper/cl_twccentos7-logs /logs xfs defaults 0 0 /dev/mapper/cl_twccentos7-opt_local /opt/local xfs defaults 0 0
- Disk 1 will contain the following partitions: /opt/local (40GB) and / (rest of the drive capacity)
- Disk 2 (the disk with the highest capacity) will contain the /data partition
- Disk 3 will contain the /logs partition (10 GB)
The aforementioned partitioning scheme is an example. Internal security protocols in your organization may dictate that other directories not be located in the main partition. During the installation, all applications will be installed in /opt/local. Cassandra will install by default in /var/lib. Application logs will be written to /home/twcloud.
Installing Oracle Java
From the Java version list, please check that the recommended Oracle JVM version is compatible with the TWC version you are using. It is not recommended to use OpenJDK. In order to consolidate all of the installed applications in a single location, we will be installing under /opt/local/java. To facilitate deployment, you may deploy using the associated script (install_java.sh). Oracle no longer allows direct download of their JDK, so it must be downloaded offline and placed in the same location as the imstall scripts. The installation script extracts it into the proper location, invokes the alternatives command to point the system to this instance (you may need to select it when prompted), and creates entries in /etc/environment. Upon completing the installation, issue the following command:
java -version
You should receive output such as the following:
java version "1.8.0_152" Java(TM) SE Runtime Environment (build 1.8.0_152-b13) Java HotSpot(TM) 64-Bit Server VM (build 25.152-b13, mixed mode)
If properly installed, you will see Java identified as Java HotSpot(TM)
#!/usr/bin/bash echo "==========================================" echo "Installing Oracle Java" echo "==========================================" echo "" echo " Oracle Java can no longer be dowloaded directly due to new authentication requirements" echo " After manually downloading jdk-8u152-linux-x64.tar.gz, copy it to this directory" echo "" read -p -"Press any key to continue, Ctl-C to exit ...: " -n1 -s echo "==========================================" mkdir -p /opt/local/java sudo tar xzf jdk-8u152-linux-x64.tar.gz -C /opt/local/java cd /opt/local/java/jdk1.8.0_152/ sudo alternatives --install /usr/bin/java java /opt/local/java/jdk1.8.0_152/bin/java 2 sudo alternatives --config java sudo alternatives --install /usr/bin/jar jar /opt/local/java/jdk1.8.0_152/bin/jar 2 sudo alternatives --install /usr/bin/javac javac /opt/local/java/jdk1.8.0_152/bin/javac 2 sudo alternatives --set jar /opt/local/java/jdk1.8.0_152/bin/jar sudo alternatives --set javac /opt/local/java/jdk1.8.0_152/bin/javac #sudo echo "PATH=$PATH:/opt/local/jdk1.8.0_152/bin:/opt/local/jdk1.8.0_152/jre/bin" >> /etc/environment sudo echo 'JAVA_HOME=/opt/local/java/jdk1.8.0_152' >> /etc/environment sudo echo 'JRE_HOME=/opt/local/java/jdk1.8.0_152/jre' >> /etc/environment sudo chown -R root:root /opt/local/java/jdk1.8.0_152
Installing the FlexNet server (lmadmin)
A FlexNet license server is required for TWCloud to operate. It can be installed on the same system, or on a separate machine. The automated deployment script (install_flex_centos7.sh) downloads all required components, deploys the server, creates the systemctl service entry to control it, and creates the necessary firewalld rules to allow the required traffic. The firewall rules are created for both the internal and public zones, and the script may require modification depending on which zone the interface is located. Additionally, if firewalld is not running when the installation script is executed, the rules will not be created. The script creates a user, lmadmin, which runs the lmadmin service. The FlexNet server requires the Redhat LSB core files as well as the ld-linux library in order to execute. The script is configured for Centos 7, but can be modified for a different version. In order to identify which LSB Core library is required, the following command can be issued:
sudo yum provides /lib/ld-lsb.so.3
The application should be installed in /opt/local/FNPLicenseServerManager (the installer's default location is /opt/FNPLicenseServerManager - so make sure that you change the location when prompted). All other default values presented by the installer should be accepted.
- After the lmadmin server has been installed it can be started by issuing the command:
sudo systemctl start lmadmin
- To check if the service is running, issue the following command
sudo systemctl status lmadmin
- If the service failed to start, it is often because the built-in web server cannot resolve the host name. To check if this is the case issue the following commands:
cd /opt/local/FNPLicenseServerManager/logs
tail web.log
You will see output similar to the following:
[Tue May 02 18:43:27 2017] [alert] (EAI 2)Name or service not known:
mod_unique_id: unable to find IPv4 address of "yourhostname"
Configuration Failed
Where yourhostname is the name of the host. IF this is the case, you will need to edit the /etc/hosts file and add an entry so the web server can resolve the host. The line will be in a format similar to the following:
192.168.130.10 yourhostname
#!/usr/bin/bash echo "===============" echo "Installing wget" echo "===============" sudo yum install -y wget echo "==================" echo "Installing lmadmin" echo "==================" sudo groupadd -g 510 lmadmin sudo useradd -g lmadmin -u 510 lmadmin sudo yum install -y ld-linux.so.2 #sudo yum provides /lib/ld-lsb.so.3 sudo yum install -y redhat-lsb-core-4.1-27.el7.centos.1.i686 sudo echo "lmadmin ALL=(ALL) NOPASSWD:ALL " >> /etc/sudoers # If Web GUI to Flex licensing is not a must - lmgrd can be used, can be placed in rc.local to startup on boot # usage - ./lmgrd -c PATH_TO_KEY_FILE -l PATH_TO_LOG_FILE # RW rights needed to both files echo "===========================================================" echo "Getting Linux 32-bit IPv6 version 11.14 from AWS FrontCloud" echo "===========================================================" wget http://d1g91r27pzl568.cloudfront.net/Cameo_daemon/FlexNet_11_14/ipv6/linux/lnx_32/cameo chmod +x cameo echo "========================================" echo "Getting Linux 32-bit lmgrd version 11.14" echo "========================================" wget https://d1oqhepk9od1tu.cloudfront.net/Flex_License_Server_Utilities/v11.14/linux32/lmgrd chmod +x lmgrd echo "======================================" echo "Making flex log file named FlexLog.log" echo "======================================" touch FlexLog.log chmod 664 FlexLog.log echo "==========================================" echo "Getting Linux 32-bit lmadmin version 11.14" echo "==========================================" wget https://d1oqhepk9od1tu.cloudfront.net/Flex_License_Server_Utilities/v11.14/linux32/lmadmin-i86_lsb-11_14_0_0.bin chmod +x lmadmin-i86_lsb-11_14_0_0.bin echo "=========================================" echo "Executing lmadmin version 11.14 installer" echo "IMPORTANT: Install into directory /opt/local/FNPLicenseServerManager" echo "" echo " Note: Accept all defaults for script to work properly!!!" read -p -"Press any key to continue ...: " -n1 -s echo "==========================================" sudo ./lmadmin-i86_lsb-11_14_0_0.bin sudo mkdir -p /opt/local/FNPLicenseServerManager/licenses/cameo/ sudo mv cameo /opt/local/FNPLicenseServerManager/licenses/cameo/cameo sudo mv lmgrd /opt/local/FNPLicenseServerManager/lmgrd sudo mv cameo /opt/local/FNPLicenseServerManager/cameo sudo mv FlexLog.log /opt/local/FNPLicenseServerManager/FlexLog.log sudo chown -R lmadmin:lmadmin /opt/local/FNPLicenseServerManager/ sudo chmod +x /opt/local/FNPLicenseServerManager/lib* sudo cp /opt/local/FNPLicenseServerManager/lib* /usr/lib/ echo "======================" echo "Opening firewall ports" echo "======================" sudo firewall-cmd --zone=public --add-port=8090/tcp --permanent sudo firewall-cmd --zone=public --add-port=1101/tcp --permanent sudo firewall-cmd --zone=public --add-port=27000-27009/tcp --permanent sudo firewall-cmd --zone=internal --add-port=8090/tcp --permanent sudo firewall-cmd --zone=internal --add-port=1101/tcp --permanent sudo firewall-cmd --zone=internal --add-port=27000-27009/tcp --permanent sudo systemctl restart firewalld echo "==========================================" echo "Creating systemd service - lmadmin" echo "==========================================" sudo echo "[Unit]" > /etc/systemd/system/lmadmin.service sudo echo "Description=Flexnet License Daemon" >> /etc/systemd/system/lmadmin.service sudo echo "After=network.target network.service" >> /etc/systemd/system/lmadmin.service sudo echo "" >> /etc/systemd/system/lmadmin.service sudo echo "[Service]" >> /etc/systemd/system/lmadmin.service sudo echo "User=lmadmin" >> /etc/systemd/system/lmadmin.service sudo echo "WorkingDirectory=/opt/local/FNPLicenseServerManager/" >> /etc/systemd/system/lmadmin.service sudo echo "ExecStart=/opt/local/FNPLicenseServerManager/lmadmin -allowStopServer yes" >> /etc/systemd/system/lmadmin.service sudo echo "Restart=always" >> /etc/systemd/system/lmadmin.service sudo echo "RestartSec=30" >> /etc/systemd/system/lmadmin.service sudo echo "Type=forking" >> /etc/systemd/system/lmadmin.service sudo echo "" >> /etc/systemd/system/lmadmin.service sudo echo "[Install]" >> /etc/systemd/system/lmadmin.service sudo echo "WantedBy=multi-user.target" >> /etc/systemd/system/lmadmin.service sudo echo "" >> /etc/systemd/system/lmadmin.service sudo chown root:root /etc/systemd/system/lmadmin.service sudo chmod 755 /etc/systemd/system/lmadmin.service sudo systemctl daemon-reload sudo systemctl enable lmadmin.service echo "==========================================" echo "lmadmin service installation complete"
Installing Cassandra 2.2.8
The deployment script for Cassandra downloads and installs Cassandra, the Cassandra tools, Cassandra OpsCenter, the DataStax agents (used for monitoring the performance of the node or cluster), and creates the necessary firewalld rules to allow proper operation both for a single node or a cluster installation. The service files are created in the /etc/init.d directory. Under Centos 7, the /etc/init.d/cassandra, as created by the package, has a flaw due to timing and locations of the process id and lock files, and therefore must be edited in order for the service to be properly controlled via the service command. To install, execute the installation script (install_dsc22_centos7.sh).
#!/usr/bin/bash echo "==========================================" echo "Installing Datastax Cassandra CE 2.2" echo "==========================================" echo "Creating Datastax Repository File" sudo echo "[datastax]" > /etc/yum.repos.d/datastax.repo sudo echo "name = Datastax Repo for Apache Cassandra" >> /etc/yum.repos.d/datastax.repo sudo echo "baseurl = http://rpm.datastax.com/community" >> /etc/yum.repos.d/datastax.repo sudo echo "enabled = 1" >> /etc/yum.repos.d/datastax.repo sudo echo "gpgcheck = 0" >> /etc/yum.repos.d/datastax.repo sudo yum install -y dsc22 sudo yum install -y cassandra22-tools sudo yum install -y opscenter sudo yum install -y datastax-agent sudo yum install -y nano #sudo chkconfig --add cassandra sudo chkconfig --add datastax-agent sudo chkconfig --add opscenterd echo "=======================" echo "Configuring firewall" echo "=======================" sudo firewall-cmd --zone=public --add-port=7000/tcp --permanent sudo firewall-cmd --zone=public --add-port=7001/tcp --permanent sudo firewall-cmd --zone=public --add-port=7199/tcp --permanent sudo firewall-cmd --zone=public --add-port=9042/tcp --permanent sudo firewall-cmd --zone=public --add-port=9160/tcp --permanent sudo firewall-cmd --zone=public --add-port=9142/tcp --permanent sudo firewall-cmd --zone=public --add-port=8888/tcp --permanent sudo firewall-cmd --zone=internal --add-port=7000/tcp --permanent sudo firewall-cmd --zone=internal --add-port=7001/tcp --permanent sudo firewall-cmd --zone=internal --add-port=7199/tcp --permanent sudo firewall-cmd --zone=internal --add-port=9042/tcp --permanent sudo firewall-cmd --zone=internal --add-port=9160/tcp --permanent sudo firewall-cmd --zone=internal --add-port=9142/tcp --permanent sudo firewall-cmd --zone=internal --add-port=8888/tcp --permanent echo "=====================================================" echo "Changing ownership of data and commit log directories" echo "=====================================================" sudo chown cassandra /data sudo chown cassandra /logs
Upon completion of the script execution, we must edit /etc/init.d/cassandra to resolve the service control issue. To edit the file, issue the following command:
sudo nano /etc/init.d/cassandra
Locate the line starting with
# chkconfig:
And edit it to contain the following:
# chkconfig: 2345 80 80
This will delay the execution to the appropriate point in time. Next, locate the line starting with
CASSANDRA_PROG=/usr/sbin/cassandra
And below it insert the following.
#------- Beginning of Centos7 modifications for startup script # Note start priority changed from 20 to 80 in chkconfig definition # create run dir for pid file [ -d /var/run/cassandra ] || mkdir /var/run/cassandra chown cassandra /var/run/cassandra #------ End of Centos7 modifications for startup script
Save the file. Now we must add the service to the boot process:
chkconfig --add cassandra
Now, proceed to edit /etc/cassandra/default.conf/cassandra.yaml
sudo nano /etc/cassandra/default.conf/cassandra.yaml
The first items we will be editing relate to the IP address of the Cassandra node and communications settings. In our diagram above, this IP address is 192.168.130.10. You will need to search for 3 keys in the configuration file and modify them accordingly. The seeds parameter is a comma-delimited list containing all of the seeds in the Cassandra cluster. Since our cluster consists of only the single node, it contains only one entry - our IP address. The other 2 parameters contain the IP address on which Cassandra listens for connections and the IP address to broadcast to other Cassandra nodes in the cluster. The broadcast_rpc_address may be commented out using a # character. If so, remove the "#" and make sure there are no leading spaces.
Additionally, we need to set rpc_address to 0.0.0.0 (meaning, it will listen to rpc requests on all interfaces), and start_rpc to true (so it will process rpc requests).
- seeds: "192.168.130.10"
- listen_address: 192.168.130.10
- broadcast_rpc_address: 192.168.130.10
- rpc_address: 0.0.0.0
- start_rpc: true
The next set of parameters control thresholds to ensure that the data being sent is processed properly.
- thrift_framed_transport_size_in_mb: 100
- commitlog_segment_size_in_mb: 64
- read_request_timeout_in_ms: 600000
- range_request_timeout_in_ms: 600000
- write_request_timeout_in_ms: 600000
- cas_contention_timeout_in_ms: 1000
- truncate_request_timeout_in_ms: 600000
- request_timeout_in_ms: 600000
- batch_size_warn_threshold_in_kb: 3000
- batch_size_fail_threshold_in_kb: 5000
If you have installed your commit log in its own partition, the default commit log size will be the lesser of ¼ of the partition size or 8GB. In order to ensure that the recommended 8GB is used, you must uncomment the commitlog_total_space_in_mb, such that it will show as below. However, if you are uncommenting this value, please ensure that the partition has enough space to accommodate an 8GB commit log.
- commitlog_total_space_in_mb: 8192
The next step is to point the data to the new locations. There are 3 entries which will be modified: data_file_directories, commitlog_directory, and saved_caches_directory. Search for these keys and edit them as follows:
- data_file_directories:
- /data/data - commitlog_directory: /logs/commitlog
- saved_caches_directory: /data/saved_caches
After you have made these changes, save the cassandra.yaml file. Now, start the related services, as follows:
sudo service cassandra start sudo service opscenterd start sudo service datastax-agent start
Now, proceed to check if Cassandra is running. To do this, issue the following command:
nodetool status
If the service is running, you will receive output such as below:
Datacenter: datacenter1=======================Status=Up/Down|/ State=Normal/Leaving/Joining/Moving-- Address Load Tokens Owns (effective) Host ID RackUN 127.0.0.1 128.4 KB 256 100.0% ea3f99eb-c4ad-4d13-95a1-80aec71b750f rack1
If the service is fully operational, the first 2 characters on the last line will state "UN", indicating the node's status is Up, and its state is Normal. You may also access DataStax OpsCenter from a browser at http://192.168.130.10:8888. When you first load OpsCenter, you may be asked for the IP address for the cluster (enter your local IP address, i.e. 192.168.130.10), after which time you will see a screen similar to the following:
DataStax OpsCenter.
Installing Teamwork Cloud
Initial Installation
The deployment script for TWCloud (install_twc185sp3_centos7.sh) creates a twcloud user, under which the service will run, and downloads all of the necessary files and executes the installer.
#!/usr/bin/bash echo "==========================================" echo "Installing Teamwork Cloud 18.5 SP3" echo "==========================================" echo "Creating twcloud group and user" sudo groupadd -g 511 twcloud sudo useradd -g twcloud -u 511 twcloud echo "" echo "IMPORTANT: Install into directory /opt/local/TeamworkCloud" echo " When prompted for user to run service, use twcloud" read -p -"Press any key to continue ...: " -n1 -s sudo wget http://download1.nomagic.com/twcloud185sp3/twcloud_185_sp3_installer_linux64.bin sudo chmod +x twcloud_185_sp3_installer_linux64.bin sudo ./twcloud_185_sp3_installer_linux64.bin sudo chown -R twcloud:twcloud /opt/local/TeamworkCloud/ echo "=======================" echo "Configuring firewall" echo "=======================" sudo firewall-cmd --zone=public --add-port=8111/tcp --permanent sudo firewall-cmd --zone=public --add-port=3579/tcp --permanent sudo firewall-cmd --zone=public --add-port=8555/tcp --permanent sudo firewall-cmd --zone=public --add-port=2552/tcp --permanent sudo firewall-cmd --zone=internal --add-port=8111/tcp --permanent sudo firewall-cmd --zone=internal --add-port=3579/tcp --permanent sudo firewall-cmd --zone=internal --add-port=8555/tcp --permanent sudo firewall-cmd --zone=internal --add-port=2552/tcp --permanent sudo systemctl restart firewalld
When you are installing TWCloud
- Press ENTER until the licensing agreement is accepted.
- Configure the machine IP - enter the local IP address of the machine (i.e. 192.168.130.10).
- Configure the cluster seed node IP - enter the local IP address of the machine (i.e. 19.168.130.10).
- Configure the TWCloud service owner - enter twcloud.
- Configure JAVA_HOME - it should display /opt/local/java/jdk1.8.0_152 - accept this default.
- Choose Install Folder - the default is set to /home/twcloud/TeamworkCloud. Do not accept the default, and instead enter /opt/local/TeamworkCloud.
Next, Pre-Installation Summary will appear. It should look as follows:
=============================================================================== Pre-Installation Summary ------------------------ Please Review the Following Before Continuing: Product Name: Teamwork Cloud Install Folder: /opt/local/TeamworkCloud Machine ip: "192.168.130.10" Seed node ip: "192.168.130.10" JAVA_HOME: "/opt/local/java/jdk1.8.0_152" Disk Space Information (for Installation Target): Required: 395,614,661 Bytes Available: 31,608,475,648 Bytes
Note
Anywhere where 192.168.130.10 is displayed, you must replace it with the IP address of your machine.
Post-Install Configuration
The installer has created the preliminary configuration of TWCloud. There are a few more changes which we must make to the various configurations files in order for TWCloud to be fully functional.
- /opt/local/TeamworkCloud/configuration/application.conf - configuration file for the TWCloud service.
If TWCloud is installed behind a proxy or firewall with NAT, upon the initial connection the MagicDraw client must know the external IP address to which it must connect. Search for server-broadcast-host, and enter the public IP address instead of the local IP address.
We now need to point TWCloud to the Cassandra database. Search for seeds =, which is located in the connection section. Edit the value inside the quotes to point to the listen_address you set in cassandra.yaml (i.e. seeds = ["192.168.130.10"])
A default password has been entered in the configuration file for its communication with the authorization server. It is recommended that it be changed from default. Search for CHANGE_ME, which is associated with the field pswd, and replace it with a password of your choosing.
At the bottom of the configuration file there is a section covering the authentication server (esi.auth). Make sure that the server property is pointing to the local IP address of the machine.
# Authentication Server addressesi.auth {# Authentication Server protocol, IP address and port# InetAddress.getLocalHost.getHostAddress is used if server is left emptyprotocol = "https"server = "192.168.130.10"port = "8555"# URL to Authentication Server REST API, which returns server configuration.config {path = "/authentication/.well-known/openid-configuration"}# URL to Authentication Server login page.login {path = "/authentication"}}
2. /opt/local/TeamworkCloud/AuthServer/config/authserver.properties - configuration file for Authorization service.
- server.public.host=public IP address (same as server-broadcast-host in application.conf). If you are accessing the server via a FQDN, use it instead of the IP address.
- twc.server.host=local IP address.
- If you changed the pswd field in /opt/local/TeamworkCloud/configuration/application.conf from the default, you must modify this file accordingly. Search for authentication.client.secret. Remove the leading # (to uncomment the directive), and replace the CHANGE_ME value with the same value as that in application.conf.
- If you are accessing the server by FQDN, you must edit the property authentication.redirect.uri.whitelist by adding an entry to whitelist the FQDN. For example: authentication.redirect.uri.whitelist=https://192.168.130.10:8111/twcloud_admin/,https://FQDN:8111/twcloud_admin/,https://md_redirec
3. Due to the manner in which System V services bootstrap, the default initialization of the authserver service on boot may not work. To resolve this, we provide 2 scripts: authserver and authserver-run. The authserver script needs to be placed in /etc/init.d. Due to the existence of a symbolic link to the service, it must first be removed. To properly remove the service, use the following commands:
sudo chkconfig --del authserver
unlink /etc/init.d/authserver
The authserver script is listed below:
#!/bin/bash # # /etc/init.d/authserver # # Startup script for Authentication Server # # chkconfig: 2345 50 75 # description: Starts and stops AuthServer if [[ $EUID -ne 0 ]]; then echo "Only a root user can run this script" exit 1 fi CONF_FILE=/etc/twcloud/twcloud-env if [[ ! -e "$CONF_FILE" ]]; then echo "Error: Config file $CONF_FILE missing" echo "Create it and in it specify the following environment variables:" echo "TWCLOUD_HOME - the installation directory of Teamwork Cloud" echo "TWCLOUD_OWNR - the user account under which the TWCloud and Authentication server are to run" echo "JAVA_HOME - the Java JDK or JRE installation on which to run the TWCloud and Authentication server" exit 1 fi . "$CONF_FILE" if [[ -z "$TWCLOUD_HOME" ]]; then echo "Error: TWCLOUD_HOME not set" exit 1 fi if [[ -z "$TWCLOUD_OWNR" ]]; then echo "Error: TWCLOUD_OWNR not set" exit 1 fi if [[ -z "$JAVA_HOME" ]]; then echo "Error: JAVA_HOME not set" exit 1 fi NAME=authserver DESCRIPTION="Authentication Server" AUTHSERVER_STARTUP_SCRIPT=./authserver-run TWCLOUD_OWNR_GROUP=$(id --group --name $TWCLOUD_OWNR) # Create directory for PID file if it's not there already PID_FILE_DIR="/var/run/$NAME" mkdir -p "$PID_FILE_DIR" chown $TWCLOUD_OWNR:$TWCLOUD_OWNR_GROUP "$PID_FILE_DIR" # This is passed to the startup script AUTHSERVER_PID_FILE=$PID_FILE_DIR/$NAME.pid # The number of seconds to wait for the service to shut down AUTHSERVER_STOP_PATIENCE=20 # The first existing directory is used for JAVA_HOME if needed. JVM_SEARCH_DIRS="/usr/lib/jvm/jre /usr/lib/jvm/jre-1.8.* /usr/lib/jvm/java-1.8.*/jre /usr/java/jdk1.8*" function get_ps_line_without_pid { ps -fe | grep -E "*java .*(.authentication-server)" | grep -v grep } case "$1" in start) # Check for PID file if [ -e "$AUTHSERVER_PID_FILE" ]; then echo "Cannot start: $DESCRIPTION is already running as a service (PID file found at $AUTHSERVER_PID_FILE)" exit 1 fi # Check if a non-service instance is running PS_LINE=$(get_ps_line_without_pid) if [ ! -z "$PS_LINE" ]; then echo "Cannot start: an instance of $DESCRIPTION is already running, but not as a service" exit 1 fi # Authentication server startup echo -n "Starting $DESCRIPTION: " su $TWCLOUD_OWNR -c "cd $TWCLOUD_HOME/AuthServer && '$AUTHSERVER_STARTUP_SCRIPT' $AUTHSERVER_PID_FILE &" >/var/log/authserver_startup.log 2>&1 echo "OK" ;; stop) # Check for PID file if [ ! -e "$AUTHSERVER_PID_FILE" ]; then PS_LINE=$(get_ps_line_without_pid) if [ -z "$PS_LINE" ]; then echo "Cannot stop: $DESCRIPTION is not running" else echo "Cannot stop: an instance of $DESCRIPTION is running but not as a service" fi exit 1 fi # TWCloud shutdown echo -n "Shutdown $DESCRIPTION: " su $TWCLOUD_OWNR -c "kill `cat $AUTHSERVER_PID_FILE`" su $TWCLOUD_OWNR -c "rm $AUTHSERVER_PID_FILE" # We'll wait at most $AUTHSERVER_STOP_PATIENCE seconds for t in `seq $AUTHSERVER_STOP_PATIENCE`; do sleep 1.0 if [[ ! -a $AUTHSERVER_PID_FILE ]] then break; fi done echo "OK" ;; reload|restart) $0 stop $0 start ;; status) if [ ! -e "$AUTHSERVER_PID_FILE" ]; then PS_LINE=$(get_ps_line_without_pid) if [ -z "$PS_LINE" ]; then echo "* $DESCRIPTION is not running" else echo "* $DESCRIPTION is not running as a service but another instance is present" fi exit 1 else PID=`cat $AUTHSERVER_PID_FILE` PS_LINE=`ps -fe | grep -E "^$TWCLOUD_OWNR[[:space:]]+$PID.*java .*(authentication-server)" | grep -v grep` if [ ! -z "$PS_LINE" ]; then echo "* $DESCRIPTION is running" exit 0 else echo "* $DESCRIPTION is not running but PID file is present" exit 3 fi fi exit $? ;; *) echo "Usage: `basename $0` start|stop|status|restart|reload" exit 1 esac exit 0
Having copied the script to the /etc/init.d/ directory, re-register the service with the following command:
sudo chkconfig --add authserver
and verify that it registered with the command
sudo chkconfig | grep authserver
which will return some data, containing a line similar to the following:
authserver 0:off 1:off 2:on 3:on 4:on 5:on 6:off
Please ensure that 2, 3, 4 and 5 are set to "on".
Now, we must change the execution permissions for the script by issuing the command:
sudo chmod +x /etc/init.d/authserver
Upon completion of this step, please copy the file authserver-run (listed below) to /opt/local/TeamworkCloud/AuthServer/authserver-run.
#!/bin/bash CONF_FILE=authentication-server-18.5.3.conf if [[ -e "$CONF_FILE" ]]; then echo "Sourcing $CONF_FILE" . "$CONF_FILE" else echo "Config file $CONF_FILE not present; continuing without" fi if [ -z "$JAVA_HOME" ] then echo "JAVA_HOME is not defined; set it in $CONF_FILE" echo "This environment variable must point to a directory containing a Java" echo "JRE or JDK, e.g. /usr/java/jdk1.8.0_152" exit 1 fi echo "Java opts: $JAVA_OPTS" # Make sure that the JVM is 1.7 or higher JAVA="$JAVA_HOME/bin/java" JAVA_VERSION=`"$JAVA" -version 2>&1 | sed -n -e '1{s/^java version "\(.*\)".*/\1/;p;q}'` if [[ ! "$JAVA_VERSION" =~ 1.[789] ]] then echo "JVM found at $JAVA is not a usable version (1.7 or up)" echo "Set your JAVA_HOME to point to a usable JVM, or include one in your PATH" exit 1 fi JAVA="$JAVA_HOME/bin/java" if [ ! -e "$JAVA" ] then echo "JAVA_HOME is set but no JVM was found at $JAVA" exit 1 fi $JAVA -jar $JAVA_OPTS authentication-server-18.5.3.jar & echo $! > "$@"
We must now change the ownership and execution rights for this file, as follows:
sudo chown twcloud:twcloud /opt/local/TeamworkCloud/AuthServer/authserver-runsudo chmod +x /opt/local/TeamworkCloud/AuthServer/authserver-run
To start the authserver service, execute the following command:
sudo service authserver start
To start the the teamwork cloud service, execute the command:
sudo service twcloud-svc start
To ensure the services start on reboot, execute the following commands:
sudo chkconfig twcloud-svc onsudo chkconfig authserver on
Additional information which may affect installations in restricted environments
Log Files
Teamwork Cloud executes under the twcloud user, and by default will store log files under this user's profile (/home/twcloud). There are 2 configuration files which control the location of these log files:
- /opt/local/TeamworkCloud/configuration/logback.xml controls the location of the Teamwork Cloud log files, whereas
- /opt/local/TeamworkCloud/Authserver/config/logback-spring.xml controls the location of the Authserver log files.
/opt/local/TeamworkCloud/configuration/logback.xml
In this file, there are settings for 2 log files which must be edited.
<appender name="SERVER-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"><file>${user.home}/.twcloud/18.5 sp3/server.log</file><rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"><fileNamePattern>${user.home}/.twcloud/18.5 sp3/server.%i.log.zip</fileNamePattern><minIndex>1</minIndex><maxIndex>1000</maxIndex></rollingPolicy><triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"><maxFileSize>20MB</maxFileSize></triggeringPolicy><encoder><pattern>%-5.5level %date{YYYY-MM-dd HH:mm:ss.SSS} %message [%logger{200}, %thread{10}]%n</pattern></encoder></appender><appender name="SECURITY-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"><file>${user.home}/.twcloud/18.5 sp3/security.log</file><rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"><!-- daily rollover --><fileNamePattern>${user.home}/.twcloud/18.5 sp3/security.%d{yyyy-MM-dd}.log</fileNamePattern><!-- keep 365 days' worth of history --><!-- maxHistory>365</maxHistory --></rollingPolicy><encoder><pattern>%-5.5level %date{YYYY-MM-dd HH:mm:ss.SSS} %message [%logger{200}, %thread{10}]%n</pattern></encoder></appender>
In each section, there are 2 settings which must be modified: file and fileNamePattern. The first setting (file) controls the absolute path to the latest log file. The second setting (fileNamePattern) controls the naming convention for the archiving of the log files. In most cases, it will suffice to replace the ${user.home} token with a different location, but you must ensure that the twcloud user has ownership of the target directories.
/opt/local/TeamworkCloud/Authserver/config/logback-spring.xml
This file contains one section which must be modified.
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"><file>${user.home}/.authserver/18.5.SP3/authserver.log</file><rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"><fileNamePattern>${user.home}/.authserver/18.5.SP3/authserver.%i.log.zip</fileNamePattern><minIndex>1</minIndex><maxIndex>10</maxIndex></rollingPolicy><triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"><maxFileSize>30MB</maxFileSize></triggeringPolicy><encoder><pattern>%-5.5level %date{YYYY-MM-dd HH:mm:ss.SSS} %message [%logger{0}, %thread{10}]%n</pattern></encoder></appender>
The same changes and permissions apply to the changes to this file as to those for /opt/local/TeamworkCloud/configuration/logback.xml.
Files installed on system locations
Daemon control files | Environment files | Cassandra installation |
---|---|---|
|
| Please refer to http://docs.datastax.com/en/archived/cassandra/2.2/cassandra/install/referenceInstallLocatePkg.html |
Frequently Asked Questions
I am receiving an error when trying to access the Teamwork Cloud Admin Console, before being prompted for user credentials.
This is usually caused by the authentication server not running, and depending on the browser may include a page beginning with:
{ "issystemerror": true, "data": "Class: org.springframework.web.client.ResourceAccessException
- To check if the authentication server is running, issue the command sudo service authserver status.
- If it states it is stopped, start it via the command sudo service authserver start.
- If it is running and you are receiving a browser window requesting you contact the system administrator, the cause for this may lie with the authentication.redirect.uri.whitelist field in authserver.properties.
- If you are accessing via the FQDN, and the UEL is showing the FQDN of the machine, please add it in the form of https://FQDN:8111/twcloud_admin/ and restart the authserver service via the command sudo service authserver restart.
I am unable to access the Teamwork Cloud Admin Console.
First, let's make sure that the service is running. This is done via the command sudo service twcloud-svc status. Also, make sure that the authserver service is running, via the command sudo service authserver status. If the services are running, the result of the command will be:
Running [PID]
Where PID is a number representing the process ID of the service. If the services are running, let's ensure that they are listening on the expected ports. This is done by issuing the following commands:
netstat -anp | grep tcp | grep 8111 | grep LISTENand netstat -anp | grep tcp | grep 8555 | grep LISTEN The result should be something along the lines of [root@twccentos7 ~]# netstat -anp | grep tcp | grep 8111 | grep LISTEN tcp6 0 0 :::8111 :::* LISTEN 28294/java [root@twccentos7 ~]# netstat -anp | grep tcp | grep 8555 | grep LISTEN tcp6 0 0 :::8555 :::* LISTEN 28466/java
If you get a command not found message when executing netstat, this means it is not installed on your computer. To install it, execute the following command
yum install net-tools
and then retry once the package has been installed.
If the ports are listening, then the issue relates to traffic not being allowed into the computer on these ports. This may be caused either by the Linux firewall, or by an external firewall. To temporarily turn off the Linux firewall, issue the following command:
sudo systemctl stop firewalld
If you can connect when the firewall is stopped, then you must check the firewall rules to ensure you are allowing traffic on both ports 8111 and 8555. To restart the Linux firewall issue the following command:
sudo systemctl start firewalld
If you were unable to connect, please contact your IT system administrators to ensure that they are not blocking traffic on these ports to the computer.
The following are the authserver and installation script files used in this example:
- No labels