Running the ZTPServer

Standalone - Change the ZTPServer Interface

Objective

I only want the ZTPServer process to listen on a specific network interface.

Solution

Open up the global ZTPServer configuration file:

admin@ztpserver:~# vi /etc/ztpserver/ztpserver.conf

Look for the line interface in the [server] group.

# To listen on all interfaces
interface = 0.0.0.0

# To listen on a specific interface
interface = 192.0.2.100

Restart the ztps process:

# If running in Standalone Mode, stop ztps
admin@ztpserver:~# pkill ztps

# Then start it again
admin@ztpserver:~# ztps &

Explanation

This recipe helps you define a specific interface for the ZTPServer to listen on.

Note

Be sure the interface coincides with the server_url value in the configuration file.

Standalone - Run ZTPServer on a Specific Port

Objective

I want to define which port the ZTPServer listens on.

Solution

Open up the global ZTPServer configuration file:

admin@ztpserver:~# vi /etc/ztpserver/ztpserver.conf

Look for the line port in the [server] group.

# Choose a port of your liking
port = 8080

Restart the ztps process:

# If running in Standalone Mode, stop ztps
admin@ztpserver:~# pkill ztps

# Then start it again
admin@ztpserver:~# ztps &

Explanation

This recipe helps you define a specific port for the ZTPServer to listen on.

Note

Be sure the port coincides with the server_url value in the configuration file.

Standalone - Run ZTPServer in a Sub-directory

Objective

I don’t want to run the ZTPServer at the root of my domain, I want it in a sub-directory.

Solution

Open up the global ZTPServer configuration file:

admin@ztpserver:~# vi /etc/ztpserver/ztpserver.conf

Look for the line server_url in the [default] group.

# Choose a subdirectory
server_url = http://ztpserver:8080/not/in/root/anymore

Restart the ztps process:

# If running in Standalone Mode, stop ztps
admin@ztpserver:~# pkill ztps

# Then start it again
admin@ztpserver:~# ztps &

Explanation

The server_url key defines where the REST API lives. You do not need to change any of your file locations to affect change. Simply change the key above.

Note

You can confirm the change by doing a simple wget http://server:port/new/directory/path/bootstrap to retrieve the bootstrap script.

Apache - Run ZTPServer on a Specific Port

Objective

I’m running ZTPServer as a WSGI with Apache and want to change what port it listens on.

Solution

Apache configurations can vary widely, and the ZTPServer has no control over this, so view this simply as a suggestion.

Open up your Apache configuration file:

# Apache
admin@ztpserver:~# vi /etc/apache2/sites-enabled/ztpserver.conf

# HTTPd
admin@ztpserver:~# vi /etc/httpd/conf.d/ztpserver.conf

Change the Listen and VirtualHost values to the desired port.

LoadModule wsgi_module modules/mod_wsgi.so
Listen 8080

<VirtualHost *:8080>

    WSGIDaemonProcess ztpserver user=www-data group=www-data threads=50
    WSGIScriptAlias / /etc/ztpserver/ztpserver.wsgi
    # Required for RHEL
    #WSGISocketPrefix /var/run/wsgi

    <Location />
        WSGIProcessGroup ztpserver
        WSGIApplicationGroup %{GLOBAL}

        # For Apache <= 2.2, use Order and Allow
        Order deny,allow
        Allow from all
        # For Apache >= 2.4, Allow is replaced by Require
        Require all granted
    </Location>

    # Override default logging locations for Apache
    #ErrorLog /path/to/ztpserver_error.log
    #CustomLog /path/to/ztpserver_access.log
</VirtualHost>

Restart the ztps process:

# Restart Apache
admin@ztpserver:~# service apache2 restart

Explanation

When you run ZTPServer as a WSGI under Apache or like server, the interface and port that are used for listening for HTTP requests are controlled by the web server. The config snippet above shows how this might be done with Apache, but note that variations might arise in your own environment.

Apache - Run ZTPServer in a Sub-directory

Objective

I’m running ZTPServer as a WSGI with Apache and I want to change the path that the REST API resides.

Solution

WSGI-compliant webserver configurations can vary widely, so here’s a sample of how this is done with Apache.

Open up the global ZTPServer configuration file:

admin@ztpserver:~# vi /etc/ztpserver/ztpserver.conf

Look for the line server_url in the [default] group.

# Choose a subdirectory
server_url = http://ztpserver:8080/not/in/root/anymore

You might think that you have to change your Apache conf to move this to a sub-directory, but you don’t. Your config should look like the block below. Note the <Location />.

LoadModule wsgi_module modules/mod_wsgi.so
Listen 8080

<VirtualHost *:8080>

    WSGIDaemonProcess ztpserver user=www-data group=www-data threads=50
    WSGIScriptAlias / /etc/ztpserver/ztpserver.wsgi
    # Required for RHEL
    #WSGISocketPrefix /var/run/wsgi

    <Location />
        WSGIProcessGroup ztpserver
        WSGIApplicationGroup %{GLOBAL}

        # For Apache <= 2.2, use Order and Allow
        Order deny,allow
        Allow from all
        # For Apache >= 2.4, Allow is replaced by Require
        Require all granted
    </Location>

    # Override default logging locations for Apache
    #ErrorLog /path/to/ztpserver_error.log
    #CustomLog /path/to/ztpserver_access.log
</VirtualHost>

Restart the ztps process:

# Restart Apache
admin@ztpserver:~# service apache2 restart

Explanation

It might seem counter-intuitive but the Apache configuration should use the Location directive to point at root. The desired change to the path is done by the ZTPServer server_url configuration value in /etc/ztpserver/ztpserver.conf.

Change ZTPServer File Ownership

Objective

I’d like all of the ZTPServer provisioning files to be owned by a particular user/group.

Note

This is most often needed when running the ZTPServer WSGI App and the apache user is unable to read/write to /usr/share/ztpserver.

Solution

admin@ztpserver:~# chown -R myUser:myGroup /usr/share/ztpserver
admin@ztpserver:~# chmod -R ug+rw /usr/share/ztpserver

Explanation

The shell commands listed above set ownership and permissions for the default data_root location /usr/share/ztpserver. Be mindful that if you are running the ZTPServer WSGI App, the mod_wsgi daemon user must be able to read/write to these files.

Note

When running the ZTPServer WSGI App, you should also check the ownership and permission of /etc/ztpserver/ztpserver.wsgi.

Apache - Configure SELinux Permissions

Objective

My server has SELinux enabled and I’d like to set the ZTPServer file type so that Apache can read/write files in the data_root.

Note

This is most often needed when running the ZTPServer WSGI App and the apache user is unable to read/write to /usr/share/ztpserver.

Solution

# For Fedora - httpd
admin@ztpserver:~# chcon -Rv --type=httpd_sys_script_rw_t /usr/share/ztpserver

# For Ubuntu - Apache
admin@ztpserver:~# chcon -R -h system_u:object_r:httpd_sys_script_rw_t /usr/share/ztpserver

Explanation

The shell commands listed above set the SELinux file attributes so that Apache can read/write to the files. This is often the case since /usr/share/ztpserver is not in the normal operating directory /var/www/. Note that the commands above are suggestions and you might consider tweaking them to suit your own environment.