Danger

TVIP TMS Pro requires the presence and use of valid SSL certificates for both TMS and video servers

Configuration of the TVIP TMS frontend

The standard tvip-tms-standalone package uses nginx as frontend server.

• file /etc/nginx/sites-enabled/tvip-tms-bundle.conf - nginx virtual server file, requires editing only for Pro versions and when SSL connections are required.

• file /etc/nginx/tvip/tvip-tms-upstreams.conf - tvip-tms configuration file, no editing allowed, will be overwritten by tvip-tms-standalone package

• file /etc/nginx/tvip/tvip-tms-locations.conf - tvip-tms configuration file, no editing allowed, will be overwritten by tvip-tms-standalone package

The virtual server configuration contains two directives include, which implement the configuration for using the TVIP TMS, defining the behavior of the virtual server when accessing certain locations. All logic is based on proxying requests to certain microservices.

Danger

The files tvip-tms-upstreams.conf and tvip-tms-locations.conf can be updated by the installer and editing them can make TMS as inoperable.

The end points for connecting external systems are described below:

Web interfaces

• The admin web interface is available at http://tms.example.com/admin and uses the private Admin API.

• The Provider web interface is available at http://tms.example.com/provider and uses the public Provider API.

• The web interface of the client web application for PC is available at: https://tms.example.com/web-player/, it uses public TVIP API, usage with no SSL certificate is impossible.

Public APIs:

• Provider API is located at http://tms.example.com/api/provider, used by the Provider Web Interface, designed primarily for integration with Service Provider Billing.

• Stat API is located at http://tms.example.com/api/stats and can be used by billing, analysis software and other tools to collect and analyze statistics.

• The TVIP API is available at http://tms.example.com/tvipapi, and it’s used by all client devices.

Built-in documentation for public APIs:

• Documentation for Provider API is located at http://tms.example.com/provider/swagger-ui.html.

• Documentation for Stat API is located at http://tms.example.com/api/stats/swagger-ui/index.html.

Configuring SSL in nginx

The default configuration of the nginx virtual server is shown below:

include /etc/nginx/tvip/tvip-tms-upstreams.conf;

log_format  log-tms-main  '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for" "$request_id" ';

server {
  listen       80;
  server_name  localhost;

  # SSL configuration
  #
  listen 443 ssl default_server;

  ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
  ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;

  error_log  /var/log/nginx/tvip-tms.error.log warn;
  access_log  /var/log/nginx/tvip-tms.access.log  log-tms-main;

  proxy_headers_hash_max_size 1024;
  proxy_headers_hash_bucket_size 128;

  include /etc/nginx/tvip/tvip-tms-locations.conf;
}

Using commercial certificates

The certificate set consists of a root certificate, an intermediate certificate and a certificate for the domain. If your SSL provider has provided a bundle.crt file, you can go straight to configuring nginx. Otherwise, you will need to merge the three certificate types into one file.

Creating bundle.crt

You should have three files: root.crt (root certificate), intermediate.crt (intermediate certificate) and your_domain.crt, copy them together with the file .key to an arbitrary directory on your server where you want to store them.

Merging certificate files into one crt file is done with the following command:

cat root.crt intermediate.crt your_domain.crt > bundle.crt

In some cases Certification Authorities send an archive with intermediate certificate and root certificate files already merged into one file. If so, you will need to merge it with the certificate file using the following command:

cat bundle.crt your_domain.crt > bundle.crt

After that you need to download certificates to the server and change the paths in the nginx configuration file.

ssl_certificate /etc/ssl/bundle.crt;
ssl_certificate_key /etc/ssl/your_domain.key

Now you can check if nginx is configured correctly with the command

nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If everything is correct, restart nginx with the command:

nginx -s reload

Using Let’s encrypt

Installing Certbot

apt install certbot python3-certbot-nginx

Setting up and registering with Certbot

certbot register --agree-tos -m name@domain.com

• “name@domain.com” - your email address

Saving debug log to /var/log/letsencrypt/letsencrypt.log

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about our work
encrypting the web, EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: n

Getting a Let’s Encrypt certificate

certbot --nginx -d tms.example.com

• “tms.example.com” - your domain address

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator nginx, Installer nginx
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for tms.examle.com
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/tvip-tms-bundle.conf

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2

To the question of the wizard, enter the answer: 2 ( Redirect)

Check:

Check that the certbot update service is running

systemctl status certbot.timer

Using ZeroSSL service

You will need to install the acme.sh utility to obtain the certificate

Execute the installation command:

curl https://get.acme.sh | sh

Register an account at ZeroSSL:

acme.sh --issue --nginx -m user@mail.com -d  --server zerossl

• user@mail.com - your mail

Obtaining a certificate:

acme.sh --issue --nginx -m user@mail.com -d tms.example.com --server zerossl
-----END CERTIFICATE-----
[Thu Mar 16 12:50:32 UTC 2023] Your cert is in: /root/.acme.sh/tms.example.com_ecc/tms.example.com.cer
[Thu Mar 16 12:50:32 UTC 2023] Your cert key is in: /root/.acme.sh/tms.example.com_ecc/tms.example.com.key
[Thu Mar 16 12:50:32 UTC 2023] The intermediate CA cert is in: /root/.acme.sh/vj.test.jettv.org_ecc/ca.cer
[Thu Mar 16 12:50:32 UTC 2023] And the full chain certs is there: /root/.acme.sh/tms.example.com_ecc/fullchain.cer

• –nginx - type of web server

• tms.example.com - domain name for which we obtain the certificate

Copy the obtained certificates, do not use the certificate files in the ~/.acme.sh/ folder, they are for internal use only, the folder structure may change in the future.

acme.sh --install-cert -d tms.example.com --key-file /etc/ssl/tms.example.com.key  --fullchain-file /etc/ssl/fullchain.cer --reloadcmd     "service nginx force-reload"
[Thu Mar 16 13:37:14 UTC 2023] The domain 'tms.example.com' seems to have a ECC cert already, lets use ecc cert.
[Thu Mar 16 13:37:14 UTC 2023] Installing key to: /etc/ssl/tms.example.com.key
[Thu Mar 16 13:37:14 UTC 2023] Installing full chain to: /etc/ssl/fullchain.cer
[Thu Mar 16 13:37:14 UTC 2023] Run reload cmd: service nginx force-reload
[Thu Mar 16 13:37:14 UTC 2023] Reload success

Please be careful: The reloadcmd command is very important. The certificate can be automatically updated, but without the correct reloadcmd SSL certificate will not be updated after 60 days.

After that, specify the paths to the certificates in the nginx settings:

server_name         tms.example.com;
ssl_certificate     /etc/ssl/fullchain.cer;
ssl_certificate_key /etc/ssl/tms.example.com.key;

Now you can check if nginx is configured correctly with a command:

nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If everything is correct, restart nginx with the command:

nginx -s reload

Your TMS server is now available at https://tms.example.com.

Additional performance settings

If you need to improve the stability and efficiency of the nginx frontend server under conditions of high number of connections, you may need to modify the parameters already set in the configuration and explicitly set additional parameters that control how nginx uses resources of the operating system.

Processing a large number of clients requires increasing the maximum number of connections per worker process. The worker_connections directive, located in the events block of the /etc/nginx/nginx.conf configuration, is responsible for this parameter in nginx. The number of file descriptors that nginx can open for a single worker process should also be increased accordingly. The worker_rlimit_nofile parameter is responsible for this property, which should be specified in the same configuration file out of blocks. It is recommended to choose it not less than the value obtained from the calculation “value of worker_connections multiplied by 2”, for example:

# /etc/nginx/nginx.conf

...
worker_rlimit_nofile 32768

events {
  worker_connections 16384;
  ...
}

Warning

Before increasing the value of the worker_rlimit_nofile parameter, check the maximum number of file descriptors allowed by the operating system to be opened by the process using the ulimit -a command and make sure that the value output by this command is greater than the value you intend to write in the configuration.

Also, to improve performance in the /etc/nginx/sites-enabled/tvip-tms-bundle.conf configuration file, the reuseport attribute should be added to the listen directive inside the `server block:

# /etc/nginx/sites-enabled/tvip-tms-bundle.conf

server {
  ...
  listen 443 ssl default_server reuseport;
  ...
}

This attribute allows nginx to open multiple listening sockets on the same address and port - in this case, a different listening socket is opened for each worker process. Load distribution between sockets is handled by the OS kernel.

The system efficiency can also be improved by activating image and EPG caching on nginx as the most demanding units of content delivered to client devices from TMS. For this purpose, you can create an additional configuration file (e.g. /etc/nginx/tvip/tvip-tms-cached-content-location.conf), in which you can specify specific locations of cached content, nginx reverse-proxy parameters for TMS services responsible for this content, as well as caching parameters in the following form:

# /etc/nginx/tvip/tvip-tms-cached-content-location.conf:

location /image/png {
  proxy_pass      http://gateway-tvip-file-api;
  proxy_set_header HOST $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Request-Id $request_id;
  proxy_pass_request_headers      on;
  proxy_read_timeout 20s;
  proxy_ignore_headers Cache-Control Expires;
  proxy_cache ram;
  proxy_cache_key $host$uri$is_args$args;
  proxy_cache_valid 200 120m;
}

location /image/jpeg {
  proxy_pass      http://gateway-tvip-file-api;
  proxy_set_header HOST $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Request-Id $request_id;
  proxy_pass_request_headers      on;
  proxy_read_timeout 20s;
  proxy_ignore_headers Cache-Control Expires;
  proxy_cache ram;
  proxy_cache_key $host$uri$is_args$args;
  proxy_cache_valid 200 120m;
}

location /tvipapi/json/short_epg/ {
  proxy_set_header X-Request-Id $request_id;
  proxy_ignore_headers Cache-Control Expires;
  proxy_pass_request_headers      on;
  proxy_read_timeout 30s;
  proxy_cache ram;
  proxy_cache_key $host$uri$is_args$args$http_accept_language;
  proxy_cache_valid 200 5m;
  proxy_set_header  X-Real-IP       $remote_addr;
  proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_pass http://gateway-tvip-tms-tvip-api;
  proxy_set_header Host $host;
  client_max_body_size 500m;
  client_body_buffer_size 128k;
 }

location /tvipapi/json/epg/ {
  proxy_set_header X-Request-Id $request_id;
  proxy_pass_request_headers      on;
  proxy_ignore_headers Cache-Control Expires;
  proxy_read_timeout 30s;
  proxy_cache ram;
  proxy_cache_key $host$uri$http_accept_language;
  proxy_cache_valid 200 60m;
  proxy_set_header  X-Real-IP       $remote_addr;
  proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_pass http://gateway-tvip-tms-tvip-api;
  proxy_set_header Host $host;
  client_max_body_size 500m;
  client_body_buffer_size 128k;
 }

After that it is necessary to add cache parameters common for all the above mentioned endpoints to the configuration file /etc/nginx/sites-enabled/tvip-tms-bundle.conf and to include the created configuration file into its server block using the include directive:

# /etc/nginx/sites-enabled/tvip-tms-bundle.conf

proxy_cache_path /dev/shm/nginx levels=1:2 keys_zone=ram:20m inactive=120m max_size=1900m;
proxy_cache_min_uses 1;
proxy_cache_lock on;
proxy_cache_lock_timeout 1s;
proxy_temp_path off;
proxy_cache_use_stale timeout http_504 updating http_500 error http_502;

server {
  ...
  include /etc/nginx/tvip/tvip-tms-cached-content-location.conf;
}

Note

After making the above changes, a reboot of nginx is required using the command sudo systemctl nginx reload or sudo systemctl nginx restart.