Skip to content

Setup Script#

Setup TUI#

After installation, executing setup.py will launch the Setup TUI by default. The TUI will walk through the setup process step-by-step.

  1. A warning will pop up if the free disk space is less than the recommended 40 GB.

  2. The TUI will detect which operating system, init type, and Apache version are currently on the server.

  3. The third screen will gather some basic information to generate certificates.

  4. Next, pick which services should be installed for this deployment. select services

  5. Next, pick a persistence mechanism. Choose from WrenDS, an LDAP that can be installed locally or remotely, or Couchbase, an enterprise NoSQL cloud database.

  6. Finally, review the summary screen that gives an overview of the selections made during the setup process.

Setup Command Line#

If TUI is not available on your environment, it switches to command line. If you want to use command line, execute with -c argument:

/install/community-edition-setup/setup.py -c

The setup script will bring up a prompt to provide information for certificate as well as the IP Address and the hostname for the Gluu Server. Hit Enter to accept the default values.

Refer to the following table for details about available setup options:

Setup Option Explanation
Enter IP Address Used primarily by Apache httpd for the Listen directive. Use an IP address assigned to one of this server's network interfaces (usage of addresses assigned to loopback interfaces is not supported)
Enter hostname Internet-facing FQDN that is used to generate certificates and metadata. Do not use an IP address or localhost.
Enter your city or locality Used to generate X.509 certificates.
Enter your state or province two letter code Used to generate X.509 certificates.
Enter two letter Country Code Used to generate X.509 certificates.
Enter Organization Name Used to generate X.509 certificates.
Enter email address for support at your organization Used to generate X.509 certificates.
Optional: enter password for oxTrust and LDAP superuser Used as the LDAP directory manager password, and for the default admin user for oxTrust.
Install oxAuth OAuth2 Authorization Server Required. Includes Gluu's OpenID Connect provider (OP) and UMA authorization server (AS) implementations.
Install oxTrust Admin UI Required. This is the Gluu server admin dashboard.
Backend Type Required. You can choose one of Local OpenDj, Remote OpenDj, Local Couchbase (availabel if you have package at /opt/dist/couchbase), Remote Couchbase, Local MySQL, Remote MySQL, Local PgSQL, Remote PgSQL, Cloud Spanner, Spanner Emulator. Note: Some options are not available depending on your profile.
Install Apache 2 web server Required
Install Shibboleth SAML IDP Optional. Only install if a SAML identity provider (IDP) is needed.
Install oxAuth RP Optional. OpenID Connect test client: useful for test environments, for more details see here
Install Passport Optional. Install if you want to support external IDP, for instance to offer users social login.
Install Gluu Radius Optional. Installs Radius server. More information is available here

When complete, the setup script will show the selections and prompt for confirmation. If everything looks OK, select Y to finish installation.

After 5-10 minutes the following success message will appear:

Gluu Server installation successful! Point your browser to [hostname].

Avoiding common issues#

Avoid setup issues by acknowledging the following:

  • IP Address: Do not use localhost for either the IP address or hostname.

  • Hostname:

    • Make sure to choose the hostname carefully. Changing the hostname after installation is not a simple task.
    • Use a real hostname--this can always be managed via host file entries if adding a DNS entry is too much work for testing.
    • For clustered deployments, use the hostname of the cluster that will be used by applications connecting to Gluu.

Warning

Use a FQDN (fully qualified domain name) as hostname and refrain from using 127.0.0.1 as IP address or usage of private IP is not supported and not recommended.

  • Only run the setup script one time. Running the command twice will break the instance.

If a resolvable DNS host is not used, then it must be added to the hostname of the Operating System hosts file on the server running the browser.

Warning

Remove or encrypt the setup.properties.last file as it contains the clear text passwords for LDAP, admin user, keystores, and 3DES salt.

Errors can be found the the setup_errors.log file and a detailed step by step installation is found in the setup.log file under the /install/community-edition-setup folder.

Script Command Line Options#

The setup script can be used to configure your Gluu Server and to add initial data for oxAuth and oxTrust to start. If setup.properties is found in this folder, these properties will automatically be used instead of the interactive setup.

The administrator can use the following command line options to include additional components:

  • -c Switches to command line
  • -p Install Passport
  • -d specify the directory where community-edition-setup is located. Defaults to '.'
  • -f specify setup.properties file
  • -h invoke this help
  • -n no interactive prompt before install starts. Run with -f
  • -N no Apache httpd server
  • -s install the Shibboleth IDP
  • -u update hosts file with IP address/hostname
  • -w get the development head war files
  • -t Load test data
  • -x Load test data and exit
  • -stm Enable Scim Test Mode
  • -sum Enable-scim-uma-mode
  • -properties-password Provide password to decode setup.properties.last.enc
  • --import-ldif=custom-ldif-dir Render ldif templates from custom-ldif-dir and import them in LDAP
  • --listen_all_interfaces Allow the LDAP server to listen on all server interfaces. This is required for clustered installations to replicate between LDAP servers. If not enabled, the LDAP server listens only to localhost
  • ---allow-pre-released-features Enable options to install experimental features, not yet officially supported.
  • --remote-ldap Allows use of a remote LDAP server.
  • --install-local-ldap Installs a local OpenDJ LDAP server
  • --disable-local-ldap Disables installing local OpenDJ LDAP server
  • --remote-couchbase Allows use of a remote Couchbase server
  • --local-couchbase Enables installing couchbase server
  • --no-data Do not import any data to database backend, used for clustering
  • --no-oxauth Do not install oxAuth OAuth2 Authorization Server
  • --no-oxtrust "Do not install oxTrust Admin UI
  • --install-gluu-radius Install oxTrust Admin UI
  • -ip-address Used primarily by Apache httpd for the Listen directive
  • -host-name Internet-facing FQDN that is used to generate certificates and metadata
  • -org-name Organization name field used for generating X.509 certificates
  • -email Email address for support at your organization used for generating X.509 certificates
  • -city City field used for generating X.509 certificates
  • -state State field used for generating X.509 certificates
  • -country Two letters country coude used for generating X.509 certificates
  • -oxtrust-admin-password Used as the default admin user for oxTrust
  • -ldap-admin-password Used as the LDAP directory manager password
  • -application-max-ram Sets the maximum RAM value to be used
  • -local-rdbm=mysql Sets RDBMS type to MySQL
  • -rdbm-user= Credential for RDBM setup
  • -rdbm-port RDBM_PORT RDBM port
  • -rdbm-db RDBM_DB RDBM database
  • -rdbm-host RDBM_HOST RDBM host
  • --reset-rdbm-db Deletes all table on target database. Warning! You will lose all data on target database.
  • -rdbm-password= Credential for RDBM setup
  • -spanner-project Spanner project name
  • -spanner-instance Spanner instance name
  • -spanner-database Spanner database name
  • -spanner-emulator-host Use Spanner emulator host
  • -google-application-credentials Path to Google application credentials json file
  • --install-casa Install CASA
  • --install-oxd Install oxd Server
  • --install-scim Install Scim Server
  • --install-fido2 Install FIDO2
  • --oxd-use-gluu-storage Use Gluu Storage for Oxd Server
  • -couchbase-bucket-prefix Set prefix for couchbase buckets
  • -couchbase-hostname Remote couchbase server hostname
  • -couchbase-admin-user Couchbase admin user
  • -couchbase-admin-password Couchbase admin user password
  • --generate-oxd-certificate Generate certificate for oxd based on hostname
  • --dummy Dummy installation. Used for re-storing backups
  • -csx Collect setup properties, save and exit
  • -j Use Java existing on system
  • -testadmin-password Used as password for testadmin for oxTrust
  • -profile Setup profile, can take one of CE, DISA-STIG
  • -opendj-keystore-type OpenDj keystore type, ony for DISA-STIG profile and can take one of pkcs11, bcfks
  • --no-progress Use simple progress
  • -enable-script inum of scripts to enable, use comma as seperation character
  • -ox-authentication-mode Sets oxAuthenticationMode
  • -ox-trust-authentication-mode Sets oxTrustAuthenticationMode
  • --gluu-passwurd-cert Creates Gluu Passwurd API keystore
  • -properties Other properties. Example: encode_salt:Y83EBo94vj9b4iyKDX2drmZk,default_store_type:JKS

Example Command: # ./setup.py -p -s This command will install Gluu Server with Passport and Shibboleth IDP.

Note

setup.py will save an encrypted properties file named setup.properties.last.enc. The password is the same as the oxTrust admin password. Retain this password to use this file for future installations. To reuse the file, it needs to be decrypted with the following command: 

openssl enc -d -aes-256-cbc -in setup.properties.last.enc -out setup.properties.last
When prompted, enter the oxTrust admin password.