OCS Inventory NG 2.12.6 on AWS User Guide

Overview

This guide covers launching and using the OCS Inventory NG 2.12.6 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg help desk, IT service and project management listing on AWS Marketplace; you choose it as the software version when you launch.

OCS Inventory NG (Open Computers and Software Inventory Next Generation) is an open source IT asset inventory platform. Small agents on your Windows, Linux, macOS, BSD and Android machines report their hardware, installed software, network settings and devices to a central server, and a web console lets you search, group and report on the whole estate. The server has two halves and this image ships both on one instance, wired to one database: the communication server at /ocsinventory, the endpoint agents send inventories to, and the console at /ocsreports, where you read the results.

What the cloudimg image adds:

• No installer page and no default login. Upstream OCS is set up in a browser installer that asks for database details, and its console account is the published admin/admin. On this image the installer and the schema updater are not shipped. First boot creates the database from upstream's own schema and updates and replaces the admin password with one generated for your instance; admin/admin never works.
• Nothing baked into the image. The image ships an empty MariaDB data directory, no console configuration file and an empty data directory, so every instance creates its own database, certificate and administrator password on first boot.
• No database password at all. The console runs as its own system user, ocsreports, and the communication server as ocscomm. MariaDB accepts each only over the local socket from processes running as that user (unix_socket authentication), and has no network listener.
• HTTPS from the first boot, for the console and for agents. nginx serves both halves on port 443 with a certificate generated on your instance, port 80 redirects to HTTPS, and a request for a host name the instance does not serve gets no answer.
• The real client address, never a header. nginx passes the agent's connection address to the communication server, so the address OCS records for each computer cannot be forged with an X-Forwarded-For header, and the console's sign in lockout (on, 10 failures per address) counts the real address.
• Only the console's own pages run PHP. nginx runs PHP for the console's four entry points only; the configuration, include files, bundled libraries, SQL files and trick addresses answer 404, and deployment package and SNMP files are served as plain downloads, never run.
• Read only code. The console and the communication server are owned by root and read only to the services that run them.
• Cross site protection. The console's ajax handlers and its state changing links refuse requests opened from other sites.
• Metadata access blocked. nginx, PHP-FPM, Apache, MariaDB, first boot and the software index are blocked from the instance metadata service, and the AMI requires IMDSv2.
• Software index on a timer. The console's All software view is rebuilt every 30 minutes by ocs-software-index.timer, so new software appears without a cron job.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: OCS Inventory NG 2.12.6 (the upstream release OCSNG_UNIX_SERVER-2.12.6.tar.gz, checksum verified), nginx, PHP 8.3 FPM, Apache 2.4 with mod_perl for the communication server, MariaDB 10.11, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
• A security group that allows TCP 22 (SSH) from your admin network, and TCP 443 (console and agents) and TCP 80 (redirects to HTTPS) from the networks your administrators and inventoried machines are on. Keep 80 and 443 as narrow as you can.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick OCS Inventory NG 2.12.6 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large (or larger for many thousands of computers), your key pair and a security group as above.

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=ocs-inventory}]'

First boot builds the database and takes about a minute after the instance is running.

Step 2: Connect to your instance

ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

First boot creates the database, sets the password and mints the certificate; nginx, Apache and the software index start only after it has finished:

systemctl is-active nginx php8.3-fpm apache2 mariadb ocs-software-index.timer
sudo test -f /var/lib/cloudimg/ocs-inventory-ng-firstboot.done && echo FIRSTBOOT_DONE

All five are active and the first boot marker is present:

active
active
active
active
active
FIRSTBOOT_DONE

Only SSH and nginx listen on network ports. Apache (the communication server) listens on the loopback address only, behind nginx; MariaDB has no network listener at all and PHP-FPM uses a local socket (mod_perl renames the Apache processes, so they show as /usr/sbin/apach):

sudo ss -lntp | awk 'NR>1 && $4 !~ /^127\.0\.0\.5[34]/ {split($6, p, "\""); print $4, p[2]}' | sort

0.0.0.0:22 sshd
0.0.0.0:443 nginx
0.0.0.0:80 nginx
127.0.0.1:8080 /usr/sbin/apach
[::]:22 sshd
[::]:443 nginx
[::]:80 nginx

Step 4: Get your URL and password

sudo cat /root/ocs-inventory-ng-credentials.txt

The file is readable by root only:

# OCS Inventory NG 2.12.6 - generated on first boot by ocs-inventory-ng-firstboot.service
# These credentials are unique to this instance; none was baked into the image. Keep this file secret.

OCS_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/ocsreports/
OCS_ADMIN_USER=admin
OCS_ADMIN_PASSWORD=<generated on your instance>
OCS_AGENT_SERVER=https://ec2-203-0-113-10.compute-1.amazonaws.com/ocsinventory
#
# Open OCS_URL in a browser (self-signed certificate minted on this instance's first boot; port 80 redirects to https)
# and sign in with the user and password above. Then change the password (Configuration > Users > admin), or add your
# own administrators and remove admin.
# Agents: point OCS Inventory agents at OCS_AGENT_SERVER (HTTPS; give them this instance's certificate,
#         /etc/nginx/ssl/ocs.crt, or a CA-issued one - see the guide).
# MariaDB: unix socket only (no TCP listener); the console and the communication server sign in as their OS users
#          ocsreports / ocscomm (no database password). root signs in over the socket: sudo mysql ocsweb
# Configuration: /etc/ocsinventory-reports/dbconfig.inc.php (root-owned, read-only to the console)
# Software index: systemctl list-timers ocs-software-index.timer (every 30 minutes)
# Change the name it serves as:   sudo ocs-set-hostname <your-dns-name>
# User guide: https://www.cloudimg.co.uk/guides/ocs-inventory-ng-2-12-6-on-ubuntu-24-04-aws/

OCS_URL is the console and OCS_AGENT_SERVER is the address your agents report to. Both use the instance's public DNS name until you set your own (Step 8).

Step 5: Sign in and change the password

Open OCS_URL in your browser. The certificate is self signed, so your browser asks you to confirm it the first time (or install your own, Step 8). Sign in as admin with the password from Step 4.

The console opens on its dashboard, which summarises the estate. A new instance has no computers yet: they appear as soon as an agent reports (Step 6).

Add or change console users under Configuration, Users. A new instance has the one administrator account, admin:

Then make the account yours:

1. Open Configuration, Users, edit admin and set a new password, or add your own administrator account and delete admin.
2. Add a separate user for each person who uses the console instead of sharing one account. The console locks an address out for a while after 10 failed sign ins.

Step 6: Enrol your first agent

Agents send inventories to OCS_AGENT_SERVER over HTTPS. Because the certificate is generated on your instance, give each agent a copy of it so it can verify the server (or install a certificate from your own certificate authority in Step 8 and give agents that instead). Copy the certificate off the instance:

sudo cat /etc/nginx/ssl/ocs.crt

On a Debian or Ubuntu machine you want to inventory, install the agent, save the certificate as /etc/ocsinventory/cacert.pem and point the agent at your server (<your-domain> is the host name in OCS_AGENT_SERVER):

sudo apt-get install -y ocsinventory-agent
sudo install -m 0644 ocs.crt /etc/ocsinventory/cacert.pem
sudo tee /etc/ocsinventory/ocsinventory-agent.cfg >/dev/null <<'EOF'
server=https://<your-domain>/ocsinventory
ssl=1
ca=/etc/ocsinventory/cacert.pem
tag=london-office
EOF
sudo ocsinventory-agent --force

The tag is free text that groups machines in the console; set something meaningful per site or department. On Red Hat family machines the agent is in EPEL; for Windows and macOS download the agent from the OCS Inventory NG project and give it the same server address and certificate.

Within seconds the machine appears under All computers, and selecting it opens its full inventory: operating system, hardware, software, network, devices and the agent that reported it.

Inventory, All software lists every package across the estate, with how many computers have each one:

The communication server answers a plain browser request with an error by design, because agents POST compressed XML to it. You can check it and count the inventoried computers from the instance:

curl -sk -o /dev/null -w 'agent endpoint: %{http_code}\n' --resolve "$(sudo grep '^OCS_AGENT_SERVER=' /root/ocs-inventory-ng-credentials.txt | cut -d= -f2- | sed -E 's#https://([^/]+)/.*#\1#'):443:127.0.0.1" "$(sudo grep '^OCS_AGENT_SERVER=' /root/ocs-inventory-ng-credentials.txt | cut -d= -f2-)"
sudo mysql ocsweb -N -e "SELECT COUNT(*) FROM hardware"

A 400 from the endpoint is healthy, and the second line is the number of computers inventoried so far:

agent endpoint: 400
1

Step 7: The software index

The communication server stores every package an agent reports, and the console's All software view reads a separate index built from them. ocs-software-index.timer rebuilds it every 30 minutes as the ocsreports user. To rebuild it now, after enrolling a batch of machines:

sudo systemctl start ocs-software-index.service
systemctl list-timers ocs-software-index.timer --no-pager --no-legend

The timer line shows when the index runs next and when it last ran.

Step 8: Your own DNS name and certificate

Point a DNS record at the instance (an Elastic IP keeps the address stable), then set the name OCS is served as. This mints a new self signed certificate for the name, points nginx at it, updates both URLs in /root/ocs-inventory-ng-credentials.txt, and keeps the name across reboots. Give your agents the new certificate and server address afterwards:

sudo ocs-set-hostname <your-domain>

To use a certificate from a public or internal certificate authority instead, copy it over the generated pair and reload nginx (running ocs-set-hostname again replaces it with a self signed one). Agents then need that authority's certificate as their ca:

sudo install -m 0644 <your-domain>.crt /etc/nginx/ssl/ocs.crt
sudo install -m 0600 <your-domain>.key /etc/nginx/ssl/ocs.key
sudo nginx -t && sudo systemctl reload nginx

Step 9: Security checks

nginx serves only the console's pages, its static files and the agent endpoint. The installer, the configuration, include files, bundled libraries, SQL files and trick addresses answer 404, plain HTTP redirects to HTTPS, and a request for a name the instance does not serve gets no answer at all:

H=$(sudo grep '^OCS_URL=' /root/ocs-inventory-ng-credentials.txt | cut -d= -f2- | sed -E 's#https://([^/]+)/.*#\1#')
for p in /ocsreports/ /ocsreports/install.php /ocsreports/update.php /ocsreports/dbconfig.inc.php /ocsreports/var.php /ocsreports/require/function_commun.php /ocsreports/files/ocsbase_new.sql /ocsreports/vendor/autoload.php /ocsreports/index.php/x /ocsinterface; do
  curl -sk -o /dev/null -w "%{http_code}  $p\n" --resolve "$H:443:127.0.0.1" "https://$H$p"
done
curl -s -o /dev/null -w 'http:// -> %{http_code}\n' --resolve "$H:80:127.0.0.1" "http://$H/ocsreports/"
curl -sk -o /dev/null -w 'unknown host name -> %{http_code}\n' --resolve "other.example:443:127.0.0.1" "https://other.example/" || true

200  /ocsreports/
404  /ocsreports/install.php
404  /ocsreports/update.php
404  /ocsreports/dbconfig.inc.php
404  /ocsreports/var.php
404  /ocsreports/require/function_commun.php
404  /ocsreports/files/ocsbase_new.sql
404  /ocsreports/vendor/autoload.php
404  /ocsreports/index.php/x
404  /ocsinterface
http:// -> 301
unknown host name -> 000

The credential check signs in through the real console sign in form with your password, and confirms that a wrong password and admin/admin are refused:

sudo ocs-cred-roundtrip

Every service runs with the instance metadata service blocked:

for u in nginx php8.3-fpm apache2 mariadb ocs-software-index; do echo "$u $(systemctl show -p IPAddressDeny --value $u)"; done

nginx fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32
php8.3-fpm fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32
apache2 fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32
mariadb fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32
ocs-software-index fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32

The code is owned by root, and the configuration is readable only by the console:

stat -c '%U:%G %a %n' /usr/share/ocsinventory-reports/ocsreports /usr/share/ocsinventory-reports/ocsreports/index.php /usr/share/ocsinventory-server/lib
sudo stat -c '%U:%G %a %n' /etc/ocsinventory-reports/dbconfig.inc.php

root:root 755 /usr/share/ocsinventory-reports/ocsreports
root:root 644 /usr/share/ocsinventory-reports/ocsreports/index.php
root:root 755 /usr/share/ocsinventory-server/lib
root:ocsreports 640 /etc/ocsinventory-reports/dbconfig.inc.php

Step 10: Backups and maintenance

Everything OCS stores is in the MariaDB database ocsweb (/var/lib/mysql), and the console's own files (user profiles, deployment packages, SNMP and IpDiscover data) are under /var/lib/ocsinventory-reports. Both are on the root volume, so the simplest backup is an EBS snapshot of it. For a consistent copy you can keep elsewhere:

sudo mariadb-dump --single-transaction ocsweb | gzip > <backup-dir>/ocsweb-$(date +%F).sql.gz
sudo tar -C / -czf <backup-dir>/ocs-files-$(date +%F).tar.gz var/lib/ocsinventory-reports etc/ocsinventory-reports

Operating system security updates install automatically; run sudo apt-get update && sudo apt-get upgrade to apply everything else. nginx, PHP-FPM, Apache and MariaDB restart cleanly and OCS keeps all of its data. New OCS Inventory NG releases arrive as new versions of this listing, and support can help you move your data to one.

What this image leaves out on purpose, to keep the attack surface small: the SOAP web service and the REST API and plugin installer are not shipped, deployment of packages to agents is off (OCS_OPT_DOWNLOAD 0), the console's features that run programs on the server (IpDiscover scans started from the console) are disabled, and the console's update check does not contact the internet. Ask support if you need one of them.

Step 11: Security recommendations

• Allow port 22 from your admin network only, and ports 80 and 443 only from the networks your administrators and inventoried machines are on.
• Use your own DNS name and a certificate your browsers and agents trust (Step 8).
• Change the admin password as soon as you sign in and give each person their own console user (Step 5).
• Keep the operating system patched, and snapshot the root volume regularly.

Support and licensing

OCS Inventory NG is open source under the GNU General Public License version 2, by the OCS Inventory NG project and its contributors; there is no per computer licence fee. The image ships the release exactly as published, with its bundled PHP and JavaScript libraries, minus the files listed in /usr/share/doc/ocs-inventory-ng/SOURCE.txt, which also names the release and its checksum.

• Email: support@cloudimg.co.uk
• Website: https://www.cloudimg.co.uk
• Support: 24/7, with a 24 hour response SLA

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.