Install Edge components on a node

Edge for Private Cloud v. 4.16.09

After you install the Edge apigee-setup utility on a node, use the apigee-setup utility to install one or more Edge components on the node.

The apigee-setup utility uses a command in the form:

> /opt/apigee/apigee-setup/bin/setup.sh -p component -f configFile

where component is the Edge component to install, and configFile is the silent configuration file containing the installation information. The configuration file must be accessible or readable by the "apigee" user. For example, you can create a new directory for the files, place them in the /usr/local or /usr/local/share directory, or anywhere else on the node accessible by the "apigee" user.

For example, to install the Edge Management Server:

> /opt/apigee/apigee-setup/bin/setup.sh -p ms -f /usr/local/myConfig

Installation considerations

As you write your config file, take into consideration the following options.

Setting up Postgres master-standby replication

By default, Edge installs all Postgres nodes in master mode. However, in production systems with multiple Postgres nodes, you must configure them to use master-standby replication so that if the master node fails, the standby node can continue to serve traffic.

You can enable and configure master-standby replication at install time by using properties in the silent config file. Or, you can enable master-standby replication after installation. For more, see Set up Master-Standby Replication for Postgres.

Enabling Cassandra authentication

By default, Cassandra installs without authentication enabled. That means anyone can access Cassandra. You can enable authentication after installing Edge, or as part of the installation process.

You can enable Cassandra authentication as install time by using properties in the silent config file. Or, you can enable it after installation.

For more, see Enable Cassandra authentication.

Binding the Router to a protected port

If you want to bind the Router to a protected port, such as port numbers less than 1024, then you have to configure the Router to run as a user with access to those ports. By default, the Router runs as the user "apigee" which does not have access to privileged ports.

To run the Router as a different user:

As root, create the file /opt/apigee/etc/edge-router.d/RUN_USER.sh.
Add the following entry to the file:
RUN_USER=root
If you do not want to run the Router as root, specify a user with access to the port.
Save the file.
If you specified a user other than root, change the owner of the file to that user:
> chown USER:USER /opt/apigee/etc/edge-router.d/RUN_USER.sh
Restart router:
> /opt/apigee/apigee-service/bin/apigee-service edge-router restart

Specifying the components to install

The following table lists the options you pass to the -p option of the apigee-service utility to specify which components to install on the node:

Component	Description
c	Install Cassandra only.
zk	install ZooKeeper only.
ds	Install ZooKeeper and Cassandra.
ld	Install OpenLDAP only.
ms	Install Edge Management Server, which also installs the Edge UI and OpenLDAP. If you set USE_LDAP_REMOTE_HOST=y in the config file, then OpenLDAP installation is skipped and the Management Server uses OpenLDAP installed on a different node.
r	Install Edge Router only.
mp	Install Edge Message Processor only.
rmp	Install Edge Router and Message Processor.
ui	Install the Edge UI.
qs	Install Qpid Server only.
ps	Install Postgres Server only.
sax	Install the analytics components, meaning Qpid and Postgres. Use this option for development and testing only, not for production.
mo	Install Monetization.
sa	Install Edge standalone, meaning Cassandra, ZooKeeper, Management Server, OpenLDAP, Edge UI, Router, and Message Processor. This option omits the Edge analytics components: Qpid and Postgres. Use this option for development and testing only, not for production.
aio	Install all components on a single node. Use this option for development and testing only, not for production.

Creating a configuration file

The configuration file contains all the information necessary to install Edge. You can often use the same configuration file to install all components in an Edge installation.

However, you will have to use different configuration files, or modify your configuration file, if:

You are installing multiple OpenLDAP servers and need to configure replication as part of a 13-node installation. Each file requires different values for LDAP_SID and LDAP_PEER.
You are creating multiple data centers as part of a 12-node installation. Each data center requires different settings for properties such as ZK_CLIENT_HOSTS and CASS_HOSTS.

Example configuration file

Shown below is an example of a complete silent configuration file for a 9 node Edge installation. Edit this file as necessary for your configuration. Use the -f option to setup.sh to include this file. Also shown below are example configuration files for each Edge topology.

# IP address or DNS name of nodes.
IP1=192.168.1.1  # Management Server, OpenLDAP, UI, ZooKeeper, Cassandra
IP2=192.168.1.2  # ZooKeeper, Cassandra
IP3=192.168.1.3  # ZooKeeper, Cassandra
IP4=192.168.1.4  # Router, Message Processor
IP5=192.168.1.5  # Router, Message Processor
IP6=192.168.1.6  # Qpid
IP7=192.168.1.7  # Qpid
IP8=192.168.1.8  # Postgres
IP9=192.168.1.9  # Postgres

# Must resolve to IP address or DNS name of host - not to 127.0.0.1 or localhost.
HOSTIP=$(hostname -i)

# Set Edge sys admin credentials.
ADMIN_EMAIL=your@email.com
APIGEE_ADMINPW=yourPassword    # If omitted, you are prompted for it.

# Location of Edge license file.
LICENSE_FILE=/tmp/license.txt

# Management Server information.
MSIP=$IP1    # IP or DNS name of Management Server node. 
# Specify the port the Management Server listens on for API calls.
# APIGEE_PORT_HTTP_MS=8080    # Default is 8080.

#
# OpenLDAP information.
#
# Set to y if you are connecting to a remote LDAP server. 
# If n, Edge installs OpenLDAP when it installs the Management Server.
USE_LDAP_REMOTE_HOST=n 

# If connecting to remote OpenLDAP server, specify the IP/DNS name and port.
# LDAP_HOST=$IP1    # IP or DNS name of OpenLDAP node.
# LDAP_PORT=10389   # Default is 10389.
APIGEE_LDAPPW=yourLdapPassword

# Specify OpenLDAP without replication, 1, or with replication, 2.
LDAP_TYPE=1 

# Set only if using replication.
# LDAP_SID=1    # Unique ID for this LDAP server. 
# LDAP_PEER=    # IP or DNS name of LDAP peer.

BIND_ON_ALL_INTERFACES=y 

# The Message Processor and Router pod.
MP_POD=gateway 

# The name of the region, corresponding to the data center name.
REGION=dc-1 # Use dc-1 unless installing in a 
            # multi-data center environment. 

# ZooKeeper information.
# See table below if installing in a multi-data center environment.
ZK_HOSTS="$IP1 $IP2 $IP3"         # IP/DNS names of all ZooKeeper nodes. 
ZK_CLIENT_HOSTS="$IP1 $IP2 $IP3"  # IP/DNS names of all ZooKeeper nodes.

# Cassandra information.
CASS_CLUSTERNAME=Apigee    # Default name is Apigee.

# IP addresses of the Cassandra hosts separated by spaces.
CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1"

# Set to enable Cassandra authentication.
# CASS_AUTH=y    # The default value is n.
# Cassandra uname/pword required if you enabled Cassandra authentication.
# CASS_USERNAME=
# CASS_PASSWORD=

# Use to enable Postgres master-standby replication
# when you have multiple Postgres nodes. 
# PG_MASTER=IPorDNSofNewMaster
# PG_STANDBY=IPorDNSofOldMaster

# SMTP information.
SKIP_SMTP=n       # Skip now and configure later by specifying "y".
SMTPHOST=smtp.gmail.com
SMTPUSER=your@email.com
SMTPPASSWORD=yourEmailPassword
SMTPSSL=y
SMTPPORT=465      # If no SSL, use a different port, such as 25.

The following table contains additional information about these properties:

Property	Note
IP/DNS names	Do not use a host name mapping to 127.0.0.1 or an IP address of 127.0.0.1 when specifying the IP address of a node.
ADMIN_EMAIL APIGEE_ADMINPW	The system administrator's password must be at least 8 characters long and contain one uppercase letter, one lowercase letter, one digit or one special character. If you omit the password, you will be prompted for it.
LICENSE_FILE	The location of the license file, which must be accessible to the "apigee" user. For example, store it in the /tmp directory and chmod 777 on the file. The file is copied to the Edge installation directory.
USE_LDAP_REMOTE_HOST LDAP_HOST LDAP_PORT	If USE_LDAP_REMOTE_HOST is n, Edge automatically installs OpenLDAP when it installs the Management Server. Set USE_LDAP_REMOTE_HOST to y if you are connecting to a remote LDAP server. OpenLDAP is not installed with the Management Server. If you are connecting to a remote OpenLDAP server, use LDAP_HOST and LDAP_PORT to specify the IP address or DNS name and port number of the host.
LDAP_TYPE LDAP_SID LDAP_PEER	Set LDAP_TYPE=1 for OpenLDAP with no replication. LDAP_TYPE=2 corresponds to OpenLDAP with replication. If your Edge topology uses a single OpenLDAP server, specify 1. If your Edge installation uses multiple OpenLDAP nodes, such as in a 13-node production installation, specify 2. If you enable replication, set the following properties: LDAP_SID=1 - Unique ID for this LDAP server. Each LDAP node uses a different ID. For example, set to 2 for LDAP peer. LDAP_PEER=10.0.0.1 - IP or DNS name of LDAP peer.
BIND_ON_ALL_INTERFACES	If set to "y" then the Router/Message Processor bind (listen) on all interfaces (IPs). If set to “n” then the Router/Message Processor bind (listen) on a specific interface, the IP returned by the "hostname -i" command).
MP_POD	Specify the name of the Message Processor and Router pod. By default, the name is gateway.
REGION	Region name. By convention, names are typically in the form dc-# where # corresponds to an integer value. For example, dc-1, dc-2, etc. You can use dc-1 unless installing in a multi-data center environment. In a multiple data center installation, the value is dc-1, or dc-2, etc. depending on which data center you are installing. However, you are not restricted to using only names in the form dc-#. You can use any name for the region.
ZK_HOSTS	The IP addresses or DNS names of the ZooKeeper nodes. The IP addresses or DNS names must be listed in the same order on all ZooKeeper nodes. In a multi-data center environment, list all ZooKeeper nodes from both data centers. Specify the “:observer” modifier on ZooKeeper nodes only when creating multiple data centers as described in a 12-host installation. In a single data center installation, omit that modifier. See 12-host clustered installation for more.
ZK_CLIENT_HOSTS	The IP addresses or DNS names of the ZooKeeper nodes used by this data center. The IP addresses or DNS names must be listed in the same order on all ZooKeeper nodes. In a single data center installation, these are the same nodes as specified by ZK_HOSTS. In a multi-data center environment, list only the ZooKeeper nodes in this data center. See 12-host clustered installation for more.
CASS_HOSTS	The IP addresses (not DNS names) of the Cassandra nodes. The first two nodes will be used as seed servers. The IP addresses must be listed in the same order on all Cassandra nodes. Cassandra nodes can have an optional “:dc,ra” suffix that specifies the data center and rack of the Cassandra node. Specify this modifier only when creating multiple data centers as described in a 12-host installation. In a single data center installation, omit that modifier. For example '192.168.124.201:1,1 = datacenter 1 and rack/availability zone 1, and '192.168.124.204:2,1 = datacenter 2 and rack/availability zone 1. In a multi-datacenter environment, to overcome firewall issues, CASS_HOSTS have to be ordered in a manner (as shown in above example) such that the nodes of the current datacenter are placed at the beginning. See 12-host clustered installation for more.
CASS_AUTH CASS_USERNAME CASS_PASSWORD	If you enable Cassandra authentication, CASS_AUTH=y, you can pass the Cassandra user name and password by using these properties.
PG_MASTER PG_STANDBY	Set to enable Postgres master-standby replication, in the form: PG_MASTER=*IPorDNSofNewMaster* PG_STANDBY=*IPorDNSofOldMaster*
SKIP_SMTP SMTPHOST SMTPUSER SMTPPASSWORD SMTPSSL SMTPPORT	Configure SMTP so Edge can send emails for lost passwords and other notifications. If SMTP user credentials are not required, omit SMTPUSER and SMTPPASSWORD.

Order of component installation

The order of component installation is based on your desired topology.

All of the installation example shown below assume that you are installing:

With Cassandra authentication disabled (default). See Enable Cassandra authentication for more.
With Postgres master-standby replication disabled (default). See Set up Master-Standby Replication for Postgres for more.
Message Processor and Router on the same node. If you install the Message Processors and Routers on different nodes, install all the Message Processors first, and then all the Routers.

Installation log files

By default, the setup.sh utility writes log information about the installation to:

/opt/apigee/var/log/apigee-setup/setup.log

If the user running the setup.sh utility does not have access to that directory, it writes the log to the /tmp directory as a file named setup_username.log.

If the user does not have access to /tmp, the setup.sh utility fails.