After booting the VM, run katoprocessreadyall before starting
the following configuration steps. This command returns READY when
all configured system processes have started, and is particularly
important when using kato commands in automated configuration
scripts which run immediately after boot (the --block option is useful in this
scenario).

Warning

All kato commands should be run as the stackato system user,
not as root. kato will prompt for the stackato user password if
sudo permissions are required for a specific operation.

This password is changed to match the one set for the first
administrator created in the Management Console. Once you have set
up the primary Helion Stackato admin account, use that account's password when
logging in to the VM at the command line.

In a Helion Stackato cluster, this change only happens on the node serving the
Management Console pages (which could be one of multiple
Controller nodes). In this case, it is a good
practice to log in to each node in the cluster to change the password manually
with the passwd command.

You may want or need to change the hostname of the Helion Stackato system,
either to match a DNS record you have created or just to make the system
URLs more convenient. This can be done using the kato node rename command:

$ kato node rename mynewname.example.com

This command will change the system hostname in /etc/hostname and /etc/hosts,
as well as performing some internal configuration for Helion Stackato such as generating a new
server certificate for the Management Console.

mDNS is only supported with .local hostnames. If you want to give the
VM a canonical hostname on an existing network, configure DNS and disable the 'mdns' role:

$ kato role remove mdns

Note

Helion Stackato takes a while to configure itself at boot (longer at first
boot). Check katostatus to see that core services are running
before executing katonoderename.

The Helion Stackato micro cloud
server is initially set up for DHCP and multicast DNS.
This is often sufficient for local testing, but in this configuration is
only a single node and can only be privately routed.

As you move toward production use of the server, further configuration
of IP addresses and hostnames will therefore be required. A production
Helion Stackato server will most likely be a cluster consisting of
several nodes, some of them requiring IP addresses and corresponding
hostnames.

If your server is to be exposed to the Internet, these addresses must be
routable and the hostnames must appear in the global DNS. Even if your
server will be part of a private PaaS for organizational use
only, it must still integrate fully with your network services, DHCP and
DNS in particular. Finally, in the rare case that such services are not
available, the Helion Stackato server can be configured with static IP
addresses and hostnames.

Before examining these scenarios in detail, review the separation of roles
in a cluster:

The core node which is conventionally called api.stackato-xxxx.local
in a micro cloud will be given its own hostname and IP address in a
cluster so that you can reach it from both the Management Console and the command line.

At the same time, the other nodes in the cluster will also need to
reach the core node, so whatever address is configured on its network
interface will have to be known to the network, the primary node,
and all the other nodes. This can be the same as the primary address
assigned to the core, or a secondary address used purely within
the cluster.

The router nodes, if separate from the primary, will each
require IP addresses of their own, reachable from any load balancer
and through any firewall that you put in front of them.

Where you configure these hostnames and IP addresses will depend on how
you operate your data center network. You will want to confer with your
network administrator about this, starting with the MAC address
configured for each VM in the hypervisor. If your site supports a
significant number of VMs, DHCP may be set up to map MAC addresses to IP
addresses in a particular way. For example, a certain range of MAC
addresses may be used for servers in the DMZ, and another range for
internal servers. If you follow this convention, your Helion Stackato server
will obtain an appropriate IP address automatically. DNS at your site
may establish a similar convention, which you will want to follow when
making any name or address changes within the cluster.

Having determined the hostnames of cluster nodes to be managed by
DNS, the hostname on the primary node
should be set using kato node rename.

Finally, if you must set a static IP on any cluster node, be sure to
test it before making the change permanent, otherwise you may not be
able to reach the node once it reboots. Assuming that the primary
address is on interface eth0, a secondary address 10.0.0.1/24
could be set up temporarily as follows:

Configure another cluster node using a different address on the same
subnet, and be sure that ping works correctly on the new addresses.
You should also use this opportunity to ping the router and DNS server
for this subnet. Check with your network administrator for their
addresses.

kato will verify the IP addresses given are within legal ranges,
automatically calculate the network or broadcast addresses for you, and
prompt for the 'sudo' password to write the changes.

The command can be run non-interactively with the following arguments:

--interface

--ip

--netmask

--gateway

--dns-nameservers (set empty "" to skip)

--dns-search-domains (set empty "" to skip)

--restart-network

If the IP address provided differs from the previous one, and the node
is not configured as a micro cloud, kato node migrate is run automatically.

As a precaution, the command does not automatically restart networking
services. To do so, run the following commands:

$ sudo /etc/init.d/networking restart

You will see a deprecation warning about the restart option, which
can safely be ignored in this context.

Note

If you are setting a new static IP after having configured set up a
cluster, you must reconfigure all other nodes in the cluster to use
the new MBUS IP address. Run kato node attach on all non-core nodes.

Alternatively, these changes could be made by editing the
/etc/network/interfaces file manually. For example:

When DHCP is not used, DNS server IP addresses must be set explicitly
using the dns-nameservers directive as displayed above. Multiple DNS
servers can be specified in a comma separated list.

Note

Helion Stackato clusters running on EC2 will
normally be registered with Elastic IP, which will provide local
dynamic address and DNS configuration over DHCP while publishing an
external static address for the cluster. You do not have to
configure the DNS server address in /etc/network/interfaces.

dnsmasq does not necessarily reinitialize on SIGHUP. Therefore,
run the following commands:

$ sudo /etc/init.d/dnsmasq restart

$ sudo /etc/init.d/networking restart

You can also use the sudoshutdown-r command to exercise a complete
restart. Then use ifconfig to check that the interface has been
configured, and ping to check routing to other hosts on the subnet
and out in the world. Finally, use dig@<DNSSERVERIP><HOSTNAME>
to check that DNS is resolving correctly.

In the event of troubleshooting, you can confirm which DNS servers are
being used by dnsmasq by checking the file /var/run/dnsmasq/resolv.conf.

Note

There may be a performance advantage in locally defining a private
secondary IP address (RFC 1918) for the controller so that the
other nodes can be assured of routing directly to it. See your network
administrator for advice on which addresses and subnets are
permissible. Once you have this secondary address set up, see the
/etc/hosts section for final
configuration of the server.

The /etc/hosts file is used to resolve certain essential or local
hostnames without calling upon the DNS. Unless you need to change
the local hostname, you will in general not
have to edit /etc/hosts manually, but when troubleshooting network
issues it never hurts to verify that the file is configured correctly.

As well, various components in a Cluster
rely on finding the cluster nodes in /etc/hosts:
the Cloud Controller and the RabbitMQ service in particular.

Helion Stackato will automatically configure /etc/hosts on the virtual
machine with one entry for the localhost loopback address and
another for the RFC 1918 private IP address of the cluster's Primary
node, for example 10.0.0.1 or 192.168.0.1. All communication between
cluster nodes should be strictly through their private IP addresses and
not on routable addresses provided by the DNS.

Remember that /etc/hosts does not support wildcards. You must use some
form of DNS for that.

Consider a Helion Stackato instance called stackato-test in domain
example.com. The following example is what you should expect to see
on a micro cloud installation, where all roles are running on
the same node:

On a cluster installation, the IP address in /etc/hosts will
identify the node hosting the MBUS, usually the same as the Cloud
Controller. On this node, you will see a correspondence between the
network interface eth0 address and /etc/hosts as in the above
example. On each of the other nodes in the cluster, for example DEA
nodes, eth0 will be configured with its own address on
the same subnet, but /etc/hosts will remain the same..

If modifying /etc/hosts becomes necessary because of a hostname change,
you can edit the hosts file. For example:

The Helion Stackato micro cloud uses multicast DNS. to broadcast its
generated hostname (for example, stackato-xxxx.local). This mechanism is
intended for VMs running on a local machine or subnet.

For production use, the server will need:

a public DNS record,

a wildcard CNAME record, and

a fixed IP address.

For example, a DNS zone file for stackato.example.com might
contain:

stackato.example.com IN A 10.3.30.200
*.stackato.example.com IN CNAME stackato.example.com

The wildcard CNAME record enables routing for the hostnames created for
each application pushed to Helion Stackato. If your networking policy forbids
the use of wildcard records, you will need to add DNS records for each
application pushed to Helion Stackato as well as the following two hostnames:

api. - API endpoint for clients and the URL of the Management Console (for example, api.stackato.example.com)

If you intend to expose your applications at URLs on other domains (for example,
using stackato map) add these names to the DNS zone
file as well. For example:

app.domain.com IN CNAME stackato.example.com

Firewalls and load balancers may require corresponding adjustments.

Note

If your site uses DHCP, configure a static binding to the MAC address
of the Helion Stackato VM (and be careful not to change the MAC address
accidentally through the hypervisor). If Helion Stackato is hosted on a cloud
provider, assign a fixed IP address using the platform's tools (for example,
Elastic IP on Amazon EC2 or Floating IP on OpenStack).

With DNS records in place, the multicast DNS broadcast is no longer
necessary. To turn it off on the Helion Stackato server, run the following command:

If you do not have access to a DNS server, you can use a dynamic DNS provider
to provide DNS records. You will need one that provides wildcard subdomain assignment.

Before registering your domain, be sure that your mail server will accept
email from the provider (for example support@changeip.com).

Create an account, choose a subdomain, and ensure that a wildcard
assignment is made on the subdomain to handle api and related
application subdomains. Then wait to receive the authorization email,
and verify the zone transfer before proceeding.

For situations where mDNS will not work (for example, running in a cloud hosting
environment or connecting from a Windows system without mDNS support)
but which do not merit the effort of manually configuring a DNS record
(for example, a test server) alternative methods are available.

This will change the system hostname and reconfigure some internal
Helion Stackato settings. The xip.io DNS servers will resolve the domain
10.9.8.7.xip.io and all sub-domains to 10.9.8.7. This works for
private subnets as well as public IP addresses.

Note

If your nameservers filter private IP addresses from
DNS responses to protect against DNS rebinding, *.xip.io
addresses, and other domains that use this method, will not work.

The Helion Stackato micro cloud runs with the following ports exposed:

Port

Type

Service

22

tcp

ssh

25

tcp

smtp

80

tcp

http

111

tcp

portmapper

111

udp

portmapper

443

tcp

https

3306

tcp

mysql

5432

tcp

postgresql

5678

tcp

DEA directory server

8181

tcp

upload server

9001

tcp

supervisord

On a production cluster, or a micro cloud running on a cloud hosting
provider, only ports 22 (SSH), 80 (HTTPS) and 443 (HTTPS) need to be
exposed externally (for example, for the Router / core node).

Within the cluster (behind the firewall), it is advisable to allow
communication between the cluster nodes on all ports. This can be done
safely by using the security group / security policy tools provided by
your hypervisor.

If you wish to restrict ports between some nodes (for example, if you do not
have the option to use security groups), the following summary describes
which ports are used by which components. Source nodes initiate the
communication, Destination nodes need to listen on the specified port.

Each node can be internally firewalled using iptables to apply the above rules.

Comments:

Ports 80 and 443 need only be open to the world on router nodes.

Port 4222 should be open on all nodes for NATS communication
with the MBUS IP (core Cloud Controller)

Port 9022 should be open to allow transfer of droplets to and
from the DEAs, and Cloud Controllers.

Port 7845 is required if you plan to stream logs from all nodes
in a cluster using katologtail command.

External access on port 22 can be restricted if necessary to the
subnet you expect to connect from. If you are providing the stackatossh feature to your users (recommended), define a distinct security
group for the public-facing Cloud Controller node that is the same as
a generic Helion Stackato group, but has the additional policy of allowing
SSH (Port 22) from hosts external to the cluster.

Within the cluster, port 22 should be open on all hosts to allow
administrative access over SSH. Port 22 is also used to mount
Filesystem service partitions in application containers on the DEA
nodes (via SSHFS).

The optional Harbor port service has a configurable port range
(default 41000 - 61000) which can be exposed externally if required.

In addition to the ports listed above for service nodes and gateways,
several service nodes assign a port for each individual user-requested
service instance. These ranges should be kept open between DEA nodes and
their respective service nodes. The default ranges are:

harbor: 35000 - 40000

memcached: 45001 - 50000

mongodb: 15001 - 25000

rabbit: 35001 - 40000

rabbit3: 25001 - 30000

redis: 5000 - 15000

Note

You can check the currently configured port range for each service
with katoconfig (for example, katoconfiggetredis_nodeport_range).

For security reasons, Docker application containers restrict access to
hosts on the eth0 subnet. By default, only ports and hosts for built-in
services and components (for example, service instances bound to an application)
are explicitly allowed.

To configure a cluster for host and port access, you must determine the
IP address of each DEA node using the katonodelist command and then ssh
to each DEA node. For example:

$ ssh -i myClusterPublicKey stackato@198.51.100.0

The following commands display the current configuration:

fencedocker/allowed_subnet_ips: Display a list of all allowed IP addresses. For example:

Sets the http_proxy environment variable in application containers so
that applications use the upstream proxy directly

Important

Use the --no-proxy option to specify all Controller nodes in your
cluster, or any other internal HTTP(S) services in your network which
Stackato may need to reach (e.g. internal Docker registries, services
brokers).

The --no-proxy option takes a comma-separated list of IP addresses,
hostnames, or domains. For example:

The katoopupstream_proxy command configures subsequently created
application containers with the HTTP_PROXY environment variable

You can set HTTP and HTTPS proxies just for applications (without
reconfiguring Polipo or kato) by adding
environment/app_http_proxy and environment/app_https_proxy
settings in the dea_ng config using kato config set. For example:

Adding this configuration sets the http_proxy and https_proxy
environment variables within all subsequently created application
containers, allowing them to connect to external HTTP or HTTPS resources on
networks which disallow direct connections. Unlike upstream_proxy,
this setting requires the protocol string to be set (http:// or
https://)

Helion Stackato data services do not offer any built-in redundancy. For
business-critical data storage, a high-availability database or cluster
is recommended.

To use an external database instead of the data services provided by
Stackato, specify the database credentials directly in your application
code instead of using the credentials from the VCAP_SERVICES
environment variable.

To tie external databases to Helion Stackato as a data service, see the
examples in the System Services section.

The Helion Stackato VM generates self-signed wildcard SSL certificates to match
the unique .local hostname it assigns itself at first boot. These
certificates can be found in:

/etc/ssl/certs/stackato.crt: the public certificate

/etc/ssl/private/stackato.key: the key used to generate signed certificates

Because these certificates are self-signed, rather than issued by a
certificate authority (CA), web browsers will warn that the certificate
cannot be verified and prompt the user to add a manual exception.

To avoid this, the generated certificate for the base URL of Helion Stackato
can be replaced with a signed certificate issued by a CA.

For additional Org-owned and Shared domains, SSL certificates can be
added using the SNI method described further below.

Ensure that both files are owned by root and that the permissions for
the .key file are set to 400 and of the .cert file to 644.

If you use a signed certificate and wish to enable strict SSL checking on the internal
REST interface (used for communication between the web console and controller),
run the following additional command:

You can deploy Helion Stackato with API and log endpoints on a different domain
from the deployed applications. For example, you might want to have the
API endpoint on a domain which is only resolvable within the corporate
network, limiting API access to the system and hiding the use of
Helion Stackato from application end users.

The Universal Service Broker feature
introduced in Helion Stackato 3.6.2 adds the
usbmanagement_api/cloud_controller/api parameter to the katoconfig
command. If you alias your API endpoint, the following error message may
be displayed when you try to connect to the endpoint:

Quota Plans can give all users in an organization the use of the
sudo command within application containers. This option is disabled
by default as a security precaution, and should only be enabled for
organizations where all users are trusted.

Users (without sudo permissions) can install Ubuntu
packages in application containers by requesting them in the
requirements section of an
application's manifest.yml file. The system allows
package installation only from those repositories specified in the
Allowed Repos list in the Management
Console.

This list can also be viewed and modified at the command line using
kato config. For example, to view the
current list:

By default, application containers are unable to mount external
filesystems (other than the built-in Filesystem Service) via network protocols such as NFS.

If the system has been configured to use privileged containers and sudo permissions have been
explicitly allowed in the quota, NFS partitions can be mounted in
application containers using application configuration similar to the
following excerpt from manifest.yml: