Run Wowza Streaming Engine as a named user

Running Wowza Streaming Engine™ (WSE) and WSE Manager under dedicated accounts lets you control what each service can access, keep system files safe from changes, and follow the principle of least privilege. By default, both services run as root on Linux and as LocalSystem on Windows.

The steps below walk you through setting up a dedicated account for each service on Linux and Windows. The wowzasvc account runs WSE and can write to the folders WSE changes at runtime. The wowzamanagersvc account runs WSE Manager and can write to the folders WSE Manager changes at runtime. All other installation files stay owned by root or Administrators.

 

Windows

After an update

Whether you need to do anything after you update WSE depends on the version you update to.

  • 4.12.2 or later: The update doesn't change any folder permissions. New files get the same permissions as the folder they're added to. You don't need to do anything.
  • 4.12.1 or earlier: The update tool resets the permissions for SYSTEM, Administrators, and Users on the install folder. It shouldn't change the permissions for wowzasvc or wowzamanagersvc, but to be safe, re-run step 5, Set folder permissions after every update.

Prerequisites

Before you start, you must have the following:

  • Administrator access. Run all commands in PowerShell as Administrator.
  • Your WSE version and install folder. The default install folder is C:\Program Files\Wowza Media Systems\Wowza Streaming Engine <version>.
  • A list of any storage outside the install folder. These steps cover only folders inside it. If an application's StorageDir, a DVR store, a MediaCache store, or a log path points somewhere else (including through a symlink), also give wowzasvc read-write access to that location.

1. Stop the services and find their names

The following commands list the WSE services and then stop them. The service names include the version number, for example WowzaStreamingEngine4121 and WowzaStreamingEngineManager4121. Note the names for step 6 and for Switch back to LocalSystem.

Get-Service *Wowza* | Format-Table Name, DisplayName, Status
Get-Service *Wowza* | Stop-Service

2. Set the install folder

Later steps use a $wse variable for the WSE install folder. The following command sets it to the default folder for WSE 4.12.1. If your install folder or version is different, change the path.

$wse = "C:\Program Files\Wowza Media Systems\Wowza Streaming Engine 4.12.1"

The variable lasts only for the current PowerShell window. If you open a new window, run this command again.

3. Create the WSE account

WSE needs its own local account. The script below prompts for a password and then creates the wowzasvc account. If the account already exists, skip this step.

$password = Read-Host -AsSecureString "Password for wowzasvc"
New-LocalUser -Name wowzasvc -Password $password -PasswordNeverExpires -UserMayNotChangePassword -Description "Wowza Streaming Engine service"

Record the password. You need it again in step 6 and after any password change. Don't add the account to the Administrators group.

4. Create the WSE Manager account

WSE Manager needs its own local account, separate from wowzasvc. The script below prompts for a password and then creates the wowzamanagersvc account. If the account already exists, skip this step.

$password = Read-Host -AsSecureString "Password for wowzamanagersvc"
New-LocalUser -Name wowzamanagersvc -Password $password -PasswordNeverExpires -UserMayNotChangePassword -Description "Wowza Streaming Engine Manager service"

Use a different password from the one for wowzasvc, and record it. You need it again in step 6 and after any password change. Don't add the account to the Administrators group.

5. Set folder permissions

Each service account needs to read the WSE installation and write to the folders its own service uses. The script below does the following:

  • Grants both accounts read and execute access to the installation folder.
  • Grants wowzasvc modify access to the WSE folders: conf, logs, content, applications, keys, transcoder, dvr, mediacache, stats, and backup.
  • Grants wowzamanagersvc modify access to the WSE Manager folders: manager\logs, manager\temp, and manager\wse-plugins.

If any of these folders don't exist yet, the script creates them before setting permissions.

icacls "$wse" /grant "wowzasvc:(OI)(CI)RX" "wowzamanagersvc:(OI)(CI)RX"
foreach ($d in "conf","logs","content","applications","keys","transcoder","dvr","mediacache","stats","backup") {
    New-Item -ItemType Directory -Force -Path "$wse\$d" | Out-Null
    icacls "$wse\$d" /grant "wowzasvc:(OI)(CI)M"
}
foreach ($d in "manager\logs","manager\temp","manager\wse-plugins") {
    New-Item -ItemType Directory -Force -Path "$wse\$d" | Out-Null
    icacls "$wse\$d" /grant "wowzamanagersvc:(OI)(CI)M"
}

The permission flags mean the following:

  • (OI)(CI): Object inherit and container inherit. The permission applies to all files and subfolders inside the folder, including ones created later.
  • RX: Read and execute.
  • M: Modify. The account can read, write, create, and delete files, but can't change permissions or take ownership.

icacls /grant adds these permissions to the existing ones. It doesn't remove access from other users or groups.

6. Set the services to run as the accounts

Use either the Services console or NSSM.

Services console
  1. Open services.msc.
  2. Double-click the WSE service.
  3. On the Log On tab, select This account, enter .\wowzasvc and its password, and then click OK.
  4. Double-click the WSE Manager service.
  5. On the Log On tab, select This account, enter .\wowzamanagersvc and its password, and then click OK.

Windows grants each account the Log on as a service right and displays a confirmation.

NSSM

The commands below run NSSM from the WSE and WSE Manager bin folders. Before running them:

  • Replace each password placeholder with that account's password.
  • If your version is different, replace the service names with the ones from step 1.
  • On 32-bit Windows, replace nssm_x64.exe with nssm_x32.exe.
& "$wse\bin\nssm_x64.exe" set WowzaStreamingEngine4121 ObjectName .\wowzasvc "<wowzasvc password>"
& "$wse\manager\bin\nssm_x64.exe" set WowzaStreamingEngineManager4121 ObjectName .\wowzamanagersvc "<wowzamanagersvc password>"

Confirm that both accounts have the Log on as a service right. In secpol.msc, go to Local Policies > User Rights Assignment > Log on as a service.


7. Start and verify

The following commands start the services and list the account each one runs as:

Get-Service *Wowza* | Start-Service
Get-CimInstance Win32_Service -Filter "Name like 'Wowza%'" | Format-Table Name, StartName, State

Check that the following are true.

  1. Both services are running, and StartName is .\wowzasvc for WSE and .\wowzamanagersvc for WSE Manager.
  2. icacls "$wse\manager\temp" lists wowzamanagersvc with (M) and doesn't list wowzasvc.
  3. You can change and save a setting in WSE Manager (for example, add an application).
  4. The logs show no permission errors. The command should print nothing:
    Select-String -Path "$wse\logs\*.log","$wse\manager\logs\*.log" -Pattern 'AccessDenied','Access is denied' -List | Select-Object Path

Switch back to LocalSystem

To run the services as LocalSystem again, change each service's logon account and then restart the services. Use either the Services console or NSSM.

Services console:

  1. Open services.msc.
  2. Double-click the WSE service.
  3. On the Log On tab, select Local System account, then click OK.
  4. Repeat for the WSE Manager service.
  5. Restart both services.

NSSM: The commands below change both services to LocalSystem and then restart them. If you are using version other than WSE 4.12.1, replace the service names with the ones from step 1.

& "$wse\bin\nssm_x64.exe" set WowzaStreamingEngine4121 ObjectName LocalSystem
& "$wse\manager\bin\nssm_x64.exe" set WowzaStreamingEngineManager4121 ObjectName LocalSystem
Get-Service *Wowza* | Restart-Service

You don't need to remove the accounts or their folder permissions. LocalSystem can still use every folder in the installation.

Run from the command line (optional)

To run WSE or WSE Manager from the command line as its account, start its script with runas. No script edits are needed. Each script opens in a new console window.

WSE:

runas /user:wowzasvc "<install folder>\bin\startup.bat"

WSE Manager:

runas /user:wowzamanagersvc "<install folder>\manager\bin\startmgr.bat"

Linux

Xilinx (AMD) U30 servers: If your server runs the xrmd service, keep WSE running as root and don't follow these steps. The WSE start script restarts xrmd with systemctl, which a non-root account can't do.

After an update

  • Updating to 4.12.2 or later: Existing files and folders keep their owner and permissions. Files and folders that the update adds get the owner and group of the folder they're in. No extra step is needed.
  • Updating to 4.12.1 or earlier: The update tool sets the owner of every file in the install folder, including existing files, to the owner of lib/wms-server.jar (root), and follows symlinks while doing so. Folders keep their owner, but the accounts can no longer change existing files such as conf/*.xml. After every update with one of these versions:
    1. Wait for the update tool's permission script to finish. The update tool starts this script in the background and exits without waiting for it. The following command returns when the script finishes:
      while pgrep -f updatepermissions.sh > /dev/null; do sleep 2; done
    2. Re-run step 5, Set file ownership and permissions.
    3. Start the services.

Updates don't affect the drop-in files. The update tool refreshes only the copies of the unit files in bin/ and manager/bin/, not the installed units or the drop-ins.

If you edited the start scripts to run WSE from the command line, see also Run from the command line, After an update.

Prerequisites

Before you start, you must have the following:

  • Root or sudo access.
  • Your WSE version and install path. The examples use the symlink /usr/local/WowzaStreamingEngine, which the installer points to the versioned install folder (for example, /usr/local/WowzaStreamingEngine-4.12.1).
  • systemd 229 or later (231 or later on Amazon Linux and Ubuntu 22.04). To check, run systemctl --version.
  • A list of any storage outside the install folder. These steps cover only folders inside it. If an application's StorageDir, a DVR store, a MediaCache store, or a log path points somewhere else (including through a symlink), also give wowzasvc read-write access to that location.

1. Stop the services

The following command stops WSE Manager and WSE:

sudo systemctl stop WowzaStreamingEngineManager WowzaStreamingEngine

2. Set the install path

Later steps use a WSE variable for the WSE install path. The following command sets it to the default symlink. If your install path is different, change it.

WSE=/usr/local/WowzaStreamingEngine

The variable lasts only for the current terminal session. If you open a new session, run this command again.

3. Create the WSE user and group

WSE needs its own system account. The command below creates wowzasvc and a group with the same name. If the account already exists, skip this step. To check, run id wowzasvc, which prints the account details if the account exists.

sudo useradd --system --user-group --create-home --home-dir /var/lib/wowzasvc --shell /usr/sbin/nologin wowzasvc

The options mean the following:

  • --system --user-group: Creates a system account with no password and a group with the same name.
  • --create-home --home-dir: Creates a home folder for the Java runtime's per-user files.
  • --shell /usr/sbin/nologin: Prevents logging in as the account.

Don't add the account to the sudo or wheel group.

4. Create the WSE Manager user and group

WSE Manager needs its own system account, separate from wowzasvc. The command below creates wowzamanagersvc and a group with the same name, using the same options as step 3. If the account already exists, skip this step. To check, run id wowzamanagersvc.

sudo useradd --system --user-group --create-home --home-dir /var/lib/wowzamanagersvc --shell /usr/sbin/nologin wowzamanagersvc

Don't add the account to the sudo or wheel group. Don't add either account to the other account's group.

5. Set file ownership and permissions

Each service account needs to read the WSE installation and own the folders its own service writes to. No other account can write anywhere in the installation. The script below:

  1. Makes root the owner of the entire installation folder. This resets any ownership given to another user earlier, for example by a cloud image or a previous run of these steps.
  2. Gives wowzasvc ownership of the WSE folders: conf, logs, content, applications, keys, transcoder, dvr, mediacache, stats, and backup.
  3. Gives wowzamanagersvc ownership of the WSE Manager folders: manager/logs, manager/temp, and manager/wse-plugins.
  4. Removes group and other write access from every file and folder, and sets every folder to drwxr-xr-x.

If any of these folders don't exist yet, the script creates them. The services create some of them on first use, which they can't do inside a root-owned folder. The script uses the WSE variable from step 2.

sudo chown -R root:root "$WSE/"
for d in conf logs content applications keys transcoder dvr mediacache stats backup; do
    sudo mkdir -p "$WSE/$d"
    sudo chown -R wowzasvc:wowzasvc "$WSE/$d"
done
for d in manager/logs manager/temp manager/wse-plugins; do
    sudo mkdir -p "$WSE/$d"
    sudo chown -R wowzamanagersvc:wowzamanagersvc "$WSE/$d"
done
sudo chmod -R go-w "$WSE/"
sudo find "$WSE/" -type d -exec chmod u+rwx,go+rx {} +

The commands work as follows:

  • "$WSE/": The trailing slash makes chown, chmod, and find follow the /usr/local/WowzaStreamingEngine symlink to the installation folder. None of the commands follow symlinks inside it, so storage reached through a symlink needs its own permissions (see Prerequisites).
  • chmod -R go-w: Removes the write access that the installer gives to everyone (drwxr-xrwx) on most folders and many files. Until this runs, wowzasvc can write to manager/temp/. The owner's access and the execute bits on scripts don't change.
  • find ... -exec chmod u+rwx,go+rx: Sets every folder to drwxr-xr-x. This also repairs transcoder/templates, which the installer may leave without execute permission (drw-r--r--), which prevents wowzasvc from opening it.

To check the result, run the following commands. The first should print nothing, and the other two should each print readable:

sudo find "$WSE/" -perm /022
sudo -u wowzasvc test -r "$WSE/lib/wms-server.jar" && echo readable
sudo -u wowzamanagersvc test -r "$WSE/manager/lib/WMSManager.war" && echo readable

6. Configure the systemd units

Each service needs a systemd drop-in that sets its account. Use drop-ins instead of editing the unit files, because WSE updates and reinstalls keep drop-ins in /etc/systemd/system. The script below:

  1. Creates a drop-in that runs WSE as wowzasvc.
  2. Creates a drop-in that runs WSE Manager as wowzamanagersvc.
  3. Reloads systemd to apply the drop-ins.

The WSE drop-in uses the full install path instead of the WSE variable, because systemd needs literal paths. If your install path is different, replace /usr/local/WowzaStreamingEngine in the WSE drop-in.

Amazon Linux and Ubuntu 22.04 only: On every start, bin/setenv.sh copies native libraries into lib-native/linux64, which wowzasvc can't write to. Before running the script, add the following line to the WSE drop-in, just above its first EOF line. The + prefix runs the copy as root before WSE starts and requires systemd 231 or later.

ExecStartPre=+/bin/bash -c '. /usr/local/WowzaStreamingEngine/bin/setenv.sh'
sudo mkdir -p /etc/systemd/system/WowzaStreamingEngine.service.d
sudo tee /etc/systemd/system/WowzaStreamingEngine.service.d/named-user.conf > /dev/null <<'EOF'
[Service]
User=wowzasvc
Group=wowzasvc
RuntimeDirectory=WowzaStreamingEngine
ExecStart=
ExecStart=/usr/local/WowzaStreamingEngine/bin/systemd.sh start /run/WowzaStreamingEngine/WowzaStreamingEngine.pid
LimitNOFILE=64000
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
EOF
sudo mkdir -p /etc/systemd/system/WowzaStreamingEngineManager.service.d
sudo tee /etc/systemd/system/WowzaStreamingEngineManager.service.d/named-user.conf > /dev/null <<'EOF'
[Service]
User=wowzamanagersvc
Group=wowzamanagersvc
LimitNOFILE=20000
EOF
sudo systemctl daemon-reload

The WSE drop-in settings mean the following:

  • User= and Group=: Run WSE as wowzasvc.
  • RuntimeDirectory= and ExecStart=: Write the PID file to /run/WowzaStreamingEngine/, which systemd creates for wowzasvc. The shipped unit writes it to /var/run/, which only root can write to. The empty ExecStart= line clears the shipped command before the new one is set.
  • LimitNOFILE=64000: Sets the open-file limit. The start script raises the limit to 64000 itself, but only root can raise it above the default hard limit.
  • AmbientCapabilities= and CapabilityBoundingSet=: Let WSE bind to ports below 1024 without root, and limit it to that one capability. The default configuration uses only ports 1024 and higher, so WSE needs this only if you configured a host port on 80, 443, or 554. Both settings require systemd 229 or later.

Don't use setcap on the Java binary instead. A file capability makes the Java runtime ignore LD_LIBRARY_PATH and LD_PRELOAD, which the WSE start scripts rely on.

7. Start and verify

The following command starts WSE and WSE Manager:

sudo systemctl start WowzaStreamingEngine WowzaStreamingEngineManager

Check that the following are true. Some commands use the WSE variable from step 2.

  1. The WSE Java process runs as wowzasvc, and the WSE Manager Java process runs as wowzamanagersvc:
    ps -o user=,pid=,args= -C java
  2. The ports are listening (1935, 8086, 8087, and 8088, plus 80, 443, or 554 if configured):
    sudo ss -ltnp | grep java
  3. Each account owns everything in its service's folders. Both commands should print nothing:
    sudo find "$WSE"/{conf,logs,content,applications,keys,transcoder,dvr,mediacache,stats,backup} ! -user wowzasvc
    sudo find "$WSE"/manager/{logs,temp,wse-plugins} ! -user wowzamanagersvc
  4. Neither account can change the installation's own files or the other service's folders. Each command should return Permission denied:
    sudo -u wowzasvc touch "$WSE/lib/test"                  # expect "Permission denied"
    sudo -u wowzasvc touch "$WSE/manager/temp/test"         # expect "Permission denied"
    sudo -u wowzamanagersvc touch "$WSE/manager/lib/test"   # expect "Permission denied"
    sudo -u wowzamanagersvc touch "$WSE/conf/test"          # expect "Permission denied"
  5. You can change and save a setting in WSE Manager (for example, add an application).
  6. The logs show no permission errors. The command should print nothing:
    grep -il 'permission denied\|AccessDenied' "$WSE"/logs/*.log "$WSE"/manager/logs/*.log

Switch back to root

To run the services as root again, remove the drop-ins from step 6 and then restart the services. The following commands remove the drop-ins, reload systemd, and restart both services:

sudo rm /etc/systemd/system/WowzaStreamingEngine.service.d/named-user.conf \
        /etc/systemd/system/WowzaStreamingEngineManager.service.d/named-user.conf
sudo systemctl daemon-reload
sudo systemctl restart WowzaStreamingEngine WowzaStreamingEngineManager

You don't need to remove the accounts or change file ownership back. Root can still use every file in the installation, including files the accounts own.

Run from the command line (optional)

Use this section if you start WSE or WSE Manager from the command line (standalone mode) instead of through the services. Stop the services first.

As shipped, bin/startup.sh runs only when started as root, and it runs WSE as root. Until you make these edits, start WSE only through its service. If you do run the unedited sudo bin/startup.sh, re-run step 5 afterward, because root owns the files it creates (logs, for example).

The edits below make each start script switch to its service's account with setpriv just before it starts Java. You still start the scripts with sudo, so the setup that needs root still works: the open-file limit, the native library copy on Amazon Linux and Ubuntu 22.04, and the Xilinx xrmd restart. WSE keeps the one capability it needs to bind to ports below 1024. If you used different account names, replace wowzasvc and wowzamanagersvc in the added lines.

  1. WSE: In /usr/local/WowzaStreamingEngine/bin/startup.sh, add one line after the line that loads setenv.sh.

    Before:

    . /usr/local/WowzaStreamingEngine/bin/setenv.sh
    mode=standalone

    After:

    . /usr/local/WowzaStreamingEngine/bin/setenv.sh
    _EXECJAVA="setpriv --reuid=wowzasvc --regid=wowzasvc --init-groups --inh-caps=+net_bind_service --ambient-caps=+net_bind_service $_EXECJAVA"
    mode=standalone
  2. WSE Manager: In /usr/local/WowzaStreamingEngine/manager/bin/startmgr.sh, add one line after ulimit -n 20000. WSE Manager uses port 8088, so it doesn't need a capability.

    Before:

    # Linux
    . /usr/local/WowzaStreamingEngine/manager/bin/setmgrenv.sh
    
    ulimit -n 20000

    After:

    # Linux
    . /usr/local/WowzaStreamingEngine/manager/bin/setmgrenv.sh
    
    ulimit -n 20000
    [ "$(id -u)" -eq 0 ] && _EXECJAVA="setpriv --reuid=wowzamanagersvc --regid=wowzamanagersvc --init-groups $_EXECJAVA"

    The WSE Manager script has no root check, so the added line switches accounts only when the script is started as root. Without this edit, you can start WSE Manager as its account with sudo -u wowzamanagersvc /usr/local/WowzaStreamingEngine/manager/bin/startmgr.sh, but the open-file limit may then stay below 20000.

  3. Start each script as usual:
    sudo /usr/local/WowzaStreamingEngine/bin/startup.sh
    sudo /usr/local/WowzaStreamingEngine/manager/bin/startmgr.sh
  4. Check which user each process runs as with ps -o user=,args= -C java.

bin/shutdown.sh and manager/bin/shutdownmgr.sh don't need any changes. Run them with sudo as before.

These edits don't affect the services. The WSE service runs bin/systemd.sh, not startup.sh. The WSE Manager service already runs startmgr.sh as wowzamanagersvc, so the added line does nothing there.

After an update

Every update installs new copies of bin/startup.sh and manager/bin/startmgr.sh, which removes your edits. The scripts then run Java as root again, and root owns the files they create. After every update:

  1. Check whether the edits are still there. A count of 0 means an edit is gone.
    grep -c setpriv /usr/local/WowzaStreamingEngine/bin/startup.sh /usr/local/WowzaStreamingEngine/manager/bin/startmgr.sh
  2. Make the edits again in the new scripts. Don't copy your old scripts over the new ones. Updates sometimes change these scripts, and an old copy can stop WSE from starting. For example, 4.12.0 changed the library versions that startmgr.sh loads.
  3. If you started either script after the update but before you reapplied the edits, re-run step 5, Set file ownership and permissions.