This tutorial uses the configuration that is similar to the first example, Hello Open Caching, but the new configuration file doesn't specify the port for the most server addresses making CP and OCN applications to use the standard port 80 for HTTP and port 443 for HTTPS.
This is the preferred way of running web services in production since these ports are open in most environments. However, one problem with this set up is that binding to the standard ports (or any ports below 1000) is a privileged operation in most of the current Linux distributions.
To deal with this issue in the most convenient and secure way, alternate ports can be defined in configuration files for all (or some) server addresses. Users then can easily switch between standard ports and alternate ports via a simple command line option. As the result, it becomes possible to switch easily between using standard ports in release mode and alternate ports in debug mode without editing the configuration file every time. This tutorial demonstrates this functionality.
Please be advised that many actions in this tutorial require root privileges.
The smoothest way to proceed is to add the current user to /etc/sudoers file
if this hasn't been done earlier.
To try running this example, open two terminal sessions, one for CP/uCDN and the other for dCDN/SP. Configure the Content Provider (CP) as follows. From the main OCS-rs repo directory, do
$ cd cp/cp_webservice
$ cp ../../examples/standard_ports/cp-svc-cfg-standard-ports.toml .
$ cp ../../examples/standard_ports/cp-db-standard-ports.json .
In the other CLI session, perform the similar procedure to start the Open Caching Node (OCN) service, the dCDN application.
$ cd ocn/ocn_webservice
$ cp ../../examples/standard_ports/ocn-svc-cfg-standard-ports.toml .
$ cp ../../examples/standard_ports/ocn-db-standard-ports.json .
Try starting the OCN web service application -
$ cargo run -- -l debug ocn-svc-cfg-standard-ports.toml
and try to run the CP application by using this command in the CP session -
$ cargo run -- -l debug cp-svc-cfg-standard-ports.toml
You should see that CP and OCN applications are failing to start with the
following error: can't start server #1, check the listener socket address.
This will happen unless you are logged in to your terminal session as the root
which in this case you shouldn't :). You can see that the application is trying
to bind the port 80 and fails because of the lack of privileges.
Now try to modify the above command lines by adding the -a (or, --use_alt_ports in the long form) flags to both of them -
$ cargo run -- -a -l debug ocn-svc-cfg-standard-ports.toml
$ cargo run -- -a -l debug cp-svc-cfg-standard-ports.toml
Now you should be able to start the applications because this flag tells OCS-rs to use the alternate ports and these are set to 8080 in the configuration files.
At this point, you can check the caching operation the same way we were doing it in the previous tutorial, Hello Open Caching.
Now let's run CP and OCN in background as systemd services. Of course, this
will only work if your Linux distribution is systemd-based! Running Open Caching
components as daemonized processes is not currently supported.
OCS-rs service installation procedure expects configuration files to have
specific names to process them. The names of configuration files can be set by
editing the values of CP_CONFIG_NAME and OCN_CONFIG_NAME keys in
../../build.env. Instead, for this example, we've chosen to simply rename our
configuration files to match the default values of these keys.
Stop the both applications by ^C and rename CP and OCN config files as follows. In CP session, do
$ mv cp-svc-cfg-standard-ports.toml cp-webservice-config.toml
and in OCN session,
$ mv ocn-svc-cfg-standard-ports.toml ocn-webservice-config.toml
From CP or OCN session window, open ../../build.env in an editor and make sure
that "DEBUG = true" statement is uncommented:
# Comment the line below to build/install release targets.
DEBUG = true
Install the both components by issuing the following command in their respective sessions -
$ cargo make install
Once this succeeds, we are ready to start our services.
CP service is named occp and OCN service is ocnode. Start CP system
service -
$ sudo service occp start
and check the service log -
$ journalctl -u occp
to verify that the server sockets are listening on the alternate port 8080. Some distributions with SELinux do not allow systemd executables to be located in user directories and that may prevent the service from starting. In this case, you will see an error similar to
occp.service: Failed to locate executable /home/dmitry/ocs-rs/cp/cp_webservice/target/debug/occp: Permission denied
in the service log. The easiest way to deal with this is to disable SELinux Enforcing mode temporarily -
sudo setenforce 0
Remember to use this setting only for debug. OCS-rs release builds do not require doing this.
Start OCN service in a similar way -
$ sudo service ocnode start
$ journalctl -u ocnode
Now you can open the Content Provider UI in the browser and try watching cached videos the same way we did in Hello Open Caching example.
When you are done, don't forget to stop the services -
$ sudo service occp stop
$ sudo service ocnode stop
For systemd services running in release mode, CP and OCN content directories are different from the locations used in debug mode. These are independent from OCS-rs repo and are defined in ../../build.env as CP_CONTENT_DIR and OCN_CONTENT_DIR respectively.
Open ../../build.env in an editor again and comment out "DEBUG = true":
# Comment the line below to build/install release targets.
#DEBUG = true
In the same file, change the OCN content directory to point to CP content to avoid video content sourcing -
- OCN_CONTENT_DIR = "${OCN_WORK_DIR}/media"
+ OCN_CONTENT_DIR = "${CP_WORK_DIR}/media"
do "make install" for both CP and OCN again -
$ cargo make install
In debug mode, the default OCS-rs content directory is located inside the git
repo tree (media). In release mode however, the OCS-rs git repo is typically
not installed on the system that runs OCS-rs components. In this mode, the
default base location for all CP service configuration and content is
/lib/occp, but this setting can be configured differently by editing the value
of CP_WORK_DIR environment variable.
In order to make the sample videos available to the CP webservice in release mode, copy the sample video content from the repo to the default CP media directory created by the install -
$ cp -r ../../media/* /lib/occp/media/
and start the services -
$ sudo service occp start
$ sudo service ocnode start
If you use journalctl to check the webservice logs at this point, you may
notice that the amount of logging in release mode is much less compared to the
debug mode. This is because the systemd service configuration doesn't include
the -l debug option to the command line. This option can be still added if
necessary by editing the systemd service configuration manually.
You can now verify that the both services listen on port 80 on all sockets except the management UI. This is possible in release mode because the install script uses libcap to set CAP_NET_BIND access capability for release executables.
Also note that both CP and OCN services run under their dedicated user account
in release mode. CP is launched under oc-cp user account and OCN runs as
oc-ocn. In contrast, in debug mode, the both services are run under the
current user.
To be able to test OCS-rs operation, copy the database JSON to the release mode base directory. Do
$ cp cp-db-standard-ports.json /lib/occp/
In CP web management UI, click on "Database Import" option and import
cp-db-standard-ports.json. After that, go to "Manage Downstream CDNs" section
from the main menu and open the configuration of the only dCDN configured
(dCDN1). You should be able to see the dCDN configuration details. Notice that
SP-OCC Host is still configured with port 8080. Since we are using standard
ports, change 8080 to 80 and hit "Update dCDN settings" button.
Similarly, in OCN web UI, copy the database configuration to the base OCN directory -
$ cp ocn-db-standard-ports.json /lib/ocnode/
and then click "Database Import" in OCN web UI and import the file. Then, click
"Manage Service Customers" option in the main menu and then click
test-service-customer1 entry. This is the bootstrap set up for our CP/uCDN.
You will see that dCDN OCC Host is configured to use port 8080. Change it to
80 and click "Update Customer Settings" button.
If you open the Content Provider web UI and go to the "Available Videos", you should see that there are no videos available. This is because the CP is configured with '/lib/occp/media/' content directory by default. We'll need to copy the test video content from the repo to that directory -
$ cp -r ../../media/* /lib/occp/media/
Refresh the page in the CP UI and the available videos should appear.
Finally, go back to CP UI and select "Manage Downstream CDNs" in the main menu.
Click dCDN1 configuration. On dCDN details page, click "Configure dCDN"
button. You should see no errors and one available redirect target that belongs
to our dCDN.
At this point, you should be able to provision and cache video content.
Try restarting the services to see that CP and OCN configuration stays persistent by using the database.
CP and OCN executable files are named the same as services, occp and ocnode.
They are installed to a regular system bin directory and become available to all
users (remember that Rust/Cargo development environment is user-specific). After
performing release install, you can run CP and OCN in foreground as any user.
Stop the services that you have started in the previous section -
$ sudo service occp stop
$ sudo service ocnode stop
and now you can simply do
$ sudo occp cp-webservice-config.toml
$ sudo ocnode ocn-webservice-config.toml
to use standard ports (running like this in production is totally NOT recommended!) or,
$ occp -a cp-webservice-config.toml
$ ocnode -a ocn-webservice-config.toml
to run with alternate ports. Don't forget to change the dCDN OCC port back to 8080 if you want to test the latter configuration.