CGRateS 0.10.5

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick CGRateS 0.10.5 on Ubuntu 24.04 as the software version and your Region, then choose Launch through EC2.

Choose m5.large, your key pair and a security group as described above. Redis keeps the tariff data and accounts on the root volume, so for production give the volume room to grow (20 GiB or more).

To launch with the AWS CLI instead, 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> \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=20,VolumeType=gp3}' \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=cgrates}]'

First boot takes well under a minute after the instance is running.

Version SSH user

CGRateS 0.10.5 on Ubuntu 24.04 ubuntu

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

First boot sets the passwords and the certificate, starts the engine, loads the sample tariff plan and then starts nginx. Check the services:

systemctl is-active redis-server cgrates nginx cgrates-firstboot
sudo test -f /var/lib/sac/data/cgrates-firstboot.done && echo FIRSTBOOT_DONE

All four units are active and the first boot marker is present:

active active active active FIRSTBOOT_DONE

Only SSH and nginx listen on network ports. The engine (2012 JSON-RPC, 2013 GOB-RPC, 2080 HTTP JSON-RPC) and Redis listen on the loopback address only:

sudo ss -lntp | awk 'NR>1 {print $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | grep -v ':53 ' | sort

0.0.0.0:22 users:(("sshd"),("systemd")) 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx")) 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx")) 127.0.0.1:2012 users:(("cgr-engine")) 127.0.0.1:2013 users:(("cgr-engine")) 127.0.0.1:2080 users:(("cgr-engine")) 127.0.0.1:6379 users:(("redis-server")) [::1]:6379 users:(("redis-server")) [::]:22 users:(("sshd"),("systemd")) [::]:443 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx")) [::]:80 users:(("nginx"),("nginx"),("nginx"),("nginx"),("nginx"))

The engine runs as the unprivileged cgrates user and reports the version:

ps -o user=,args= -C cgr-engine cgr-engine -version

cgrates /usr/bin/cgr-engine -config_path=/etc/cgrates CGRateS@v0.10.5

sudo cat /root/cgrates-credentials.txt

Only root can read the file. Secret values are shown here as examples:

# CGRateS 0.10.5 on Ubuntu 24.04 - generated on first boot by cgrates-firstboot.service.
# Every value is UNIQUE to this instance. Store them somewhere safe.
# The JSON-RPC API over HTTPS (nginx, per-instance self-signed certificate) with HTTP Basic Auth: cgrates.url=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/jsonrpc cgrates.basicauth.user=admin cgrates.basicauth.pass=<CGRATES_BASICAUTH_PASSWORD>
# Redis 7 (the CGRateS DataDB) on 127.0.0.1:6379 only, logical DB 10: cgrates.redis.pass=<redis-password>
# The engine's own listeners (127.0.0.1:2012 JSON-RPC, :2013 GOB-RPC, :2080 HTTP) are loopback only and have no authentication. # Verify the instance any time:
sudo bash /usr/local/sbin/cgrates-credcheck.sh

cgrates.url uses the instance's public DNS name from the EC2 instance metadata. The certificate also names the public and private IP addresses, so https://<public-ip>/jsonrpc works too.

If you stop and start the instance without an Elastic IP, the boot service picks up the new address and issues a new certificate for it. To serve the API under your own DNS name, see Step 8.

From your workstation, a call looks like this. The certificate is self-signed until you install your own, so pass -k or, better, download /etc/ssl/cgrates/cgrates.crt and pass --cacert.

Keep the password out of your shell history by putting it in a curl config file that only you can read:

printf 'user = "admin:%s"\n' '<CGRATES_BASICAUTH_PASSWORD>' > cgrates-curl.conf && chmod 600 cgrates-curl.conf curl -k -K cgrates-curl.conf -H 'Content-Type: application/json' \
  -d '{"id":1,"method":"CoreSv1.Ping","params":[{}]}' https://<api-host>/jsonrpc

On the instance itself, you can make the same calls through nginx. nginx refuses a request without the password, or with a wrong one, with 401 before it reaches the engine. With the instance's password, the engine answers:

U=$(sudo sed -n 's/^cgrates\.url=//p' /root/cgrates-credentials.txt); H=${U#https://}; H=${H%%/*}
CFG=$(sudo mktemp /run/cgrates-curl.XXXXXX);
sudo chown "$(id -u)" "$CFG" printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^cgrates\.basicauth\.pass=//p' /root/cgrates-credentials.txt)" > "$CFG" C=(-q -s --cacert /etc/ssl/cgrates/cgrates.crt --resolve "$H:443:127.0.0.1" -H 'Content-Type: application/json') P='{"id":1,"method":"CoreSv1.Ping","params":[{}]}' curl "${C[@]}" -o /dev/null -w '%{http_code}\n' -d "$P" "$U" curl "${C[@]}" -o /dev/null -w '%{http_code}\n' -u admin:not-the-password -d "$P" "$U" curl "${C[@]}" -K "$CFG" -d "$P" "$U"; echo
sudo rm -f "$CFG"

401 401 {"id":1,"result":"Pong","error":null}

Now ask the engine what it knows. The sample tariff plan created account 1001 in tenant cgrates.org with a monetary balance of 10. It rates calls from 1001 to 1002 at 0.40 for the first minute, then 0.20 per minute. Read the account and price a call of 1 minute 20 seconds:

U=$(sudo sed -n 's/^cgrates\.url=//p' /root/cgrates-credentials.txt); H=${U#https://}; H=${H%%/*}
CFG=$(sudo mktemp /run/cgrates-curl.XXXXXX);
sudo chown "$(id -u)" "$CFG" printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^cgrates\.basicauth\.pass=//p' /root/cgrates-credentials.txt)" > "$CFG" api() { curl -q -s --cacert /etc/ssl/cgrates/cgrates.crt --resolve "$H:443:127.0.0.1" -K "$CFG" -H 'Content-Type: application/json' -d "$1" "$U"; } api '{"id":2,"method":"APIerSv1.GetAccount","params":[{"Tenant":"cgrates.org","Account":"1001"}]}' \
  | jq '{id: .result.Id, monetary: [.result.BalanceMap | to_entries[] | select(.key|startswith("*monetary")) | .value[] | {Id, Value}], error}' api '{"id":3,"method":"APIerSv1.GetCost","params":[{"Tenant":"cgrates.org","Category":"call","Subject":"1001","AnswerTime":"2014-08-04T13:00:00Z","Destination":"1002","Usage":"1m20s"}]}' \
  | jq -c '{cost: .result.Cost, error}'
sudo rm -f "$CFG"

{ "id": "*out:cgrates.org:1001", "monetary": [ { "Id": "test", "Value": 10 } ], "error": null } {"cost":0.6334,"error":null}

On the instance, the cgr-console client talks to the engine on 127.0.0.1:2012 directly. This command prices a 20-second call. One minute is charged, which is 0.40 connect plus the first increment:

cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1002" AnswerTime="2014-08-04T13:00:00Z" Usage="20s"' | jq -c '{Cost, Usage: ([.Charges[].Increments[].Usage])}'

{"Cost":0.6,"Usage":["0s","1m0s"]}

Every JSON-RPC method of the CGRateS 0.10 API (APIerSv1.*, APIerSv2.*, SessionSv1.*, CDRsV1.* and the rest) is available through https://<api-host>/jsonrpc. The WebSocket endpoint /ws sits behind the same Basic Auth. See the CGRateS documentation at cgrates.readthedocs.io.

cgrates-credcheck.sh checks the network exposure, Redis authentication, the HTTPS front door, account 1001 and a rated call. For the front door, it confirms that requests are refused without a password and with a wrong password, and that the engine answers with the right one:

sudo bash /usr/local/sbin/cgrates-credcheck.sh

OK

A tariff plan is a directory of CSV files (Destinations.csv, Rates.csv, DestinationRates.csv, RatingPlans.csv, RatingProfiles.csv, Actions.csv, ActionPlans.csv, AccountActions.csv, Chargers.csv, Attributes.csv and so on). The sample plans that ship with CGRateS are a good starting point. List them:

ls /usr/share/cgrates/tariffplans/tutorial

AccountActions.csv ActionPlans.csv Actions.csv Attributes.csv Chargers.csv DestinationRates.csv Destinations.csv Filters.csv README.md Rates.csv RatingPlans.csv RatingProfiles.csv Resources.csv Stats.csv Suppliers.csv Thresholds.csv

Copy one into a directory you own, edit it, then load it. cgr-loader reads the Redis connection and password from the engine configuration, so no password goes on the command line. It also tells the running engine to reload its caches:

sudo cp -r /usr/share/cgrates/tariffplans/tutorial /srv/my-tariffplan
sudo cgr-loader -config_path=/etc/cgrates -path=/srv/my-tariffplan -verbose

The DataDB is Redis logical database 10. The StorDB, which holds CDRs and tariff plans kept in the database rather than in CSV files, is CGRateS's internal store.

To archive CDRs in MySQL or PostgreSQL, install the database server on localhost or point at Amazon RDS. Then change stor_db in /etc/cgrates/cgrates.json and restart the engine (sudo systemctl restart cgrates).

The engine's S3 and SQS exporters cannot use an EC2 instance role on this image, because every service is blocked from the instance metadata service. Give them an access key in the exporter configuration instead. Store it in /etc/cgrates/cgrates.json, which only root and the cgrates user can read.

Point a DNS record at the instance (an Elastic IP keeps the address stable), then set the name that the API is served as. The command creates a new self-signed certificate for the name, updates nginx and cgrates.url in /root/cgrates-credentials.txt, and keeps the name across reboots:

sudo cgrates-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 cgrates-set-hostname again replaces it with a self-signed one:

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

Plain HTTP redirects to HTTPS on the configured name. A request for any other host name is dropped without an answer, because nginx closes the connection, shown as 000:

U=$(sudo sed -n 's/^cgrates\.url=//p' /root/cgrates-credentials.txt); H=${U#https://}; H=${H%%/*} curl -q -s -o /dev/null -w 'http:// -> %{http_code} %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/jsonrpc" curl -q -s -o /dev/null -w 'unknown host -> %{http_code}\n' -H 'Host: example.com' http://127.0.0.1/ || true

http:// -> 301 https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/jsonrpc unknown host -> 000

The certificate was generated on this instance and names its own addresses:

U=$(sudo sed -n 's/^cgrates\.url=//p' /root/cgrates-credentials.txt); H=${U#https://}; H=${H%%/*} echo | openssl s_client -connect 127.0.0.1:443 -servername "$H" 2>/dev/null | openssl x509 -noout -subject -ext subjectAltName

subject=CN = ec2-<public-ip-dashed>.compute-1.amazonaws.com, O = sac X509v3 Subject Alternative Name: DNS:ec2-<public-ip-dashed>.compute-1.amazonaws.com, IP Address:<public-ip>, IP Address:<private-ip>, IP Address:127.0.0.1, DNS:localhost

None of the services can reach the instance metadata service. The engine and the first boot service are also blocked from the whole IPv4 and IPv6 link-local ranges (systemd shows 169.254.169.254/32 folded into 169.254.0.0/16). An *http_post action or an exporter URL can therefore never reach instance metadata:

systemctl show cgrates redis-server nginx cgrates-firstboot -p Id -p IPAddressDeny

IPAddressDeny=169.254.0.0/16 fe80::/10 fd00:ec2::254/128 168.63.129.16/32 Id=cgrates.service IPAddressDeny=fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32 Id=redis-server.service IPAddressDeny=fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32 Id=nginx.service IPAddressDeny=fe80::/10 fd00:ec2::254/128 168.63.129.16/32 169.254.0.0/16 Id=cgrates-firstboot.service

Actions and exporters can still reach addresses in your VPC, which is usually what you want. To stop the engine from reaching private ranges too, add them in a drop-in, for example IPAddressDeny=10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 in /etc/systemd/system/cgrates.service.d/60-private.conf, then sudo systemctl daemon-reload and sudo systemctl restart cgrates.

Every engine listener is pinned to the loopback address. The TLS variants open only if you configure a server certificate. nginx guards the whole API with Basic Auth, hands the engine the configured host name and the client address from the connection, and never forwards the client's Authorization header:

jq .listen /etc/cgrates/cgrates.json grep -E 'auth_basic|proxy_pass|proxy_set_header (Host|X-Forwarded-For|X-Real-IP|X-Forwarded-Host|Authorization) ' /etc/nginx/sites-available/sac-cgrates

{ "rpc_json": "127.0.0.1:2012", "rpc_gob": "127.0.0.1:2013", "http": "127.0.0.1:2080", "rpc_json_tls": "127.0.0.1:2022", "rpc_gob_tls": "127.0.0.1:2023", "http_tls": "127.0.0.1:2280" } auth_basic "CGRateS API"; auth_basic_user_file /etc/nginx/cgrates.htpasswd; proxy_pass http://127.0.0.1:2080; proxy_set_header Host $cgrates_host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Host ""; proxy_set_header Authorization "";

The engine's listen settings are loopback-only and have no authentication, so anyone with a shell on the instance can drive the engine. Limit SSH access to the people who administer billing, and never change a listener to a non-loopback address. Use nginx for remote access.

The secrets are stored only in files that root can read. The cgrates user can also read the engine configuration, and nginx can read the password hash:

sudo stat -c '%A %U %G %n' /root/cgrates-credentials.txt /etc/cgrates/cgrates.json /etc/nginx/cgrates.htpasswd /etc/ssl/cgrates/cgrates.key

-rw------- root root /root/cgrates-credentials.txt -rw-r----- root cgrates /etc/cgrates/cgrates.json -rw-r----- root www-data /etc/nginx/cgrates.htpasswd -rw------- root root /etc/ssl/cgrates/cgrates.key

The build records exactly what is on the image. The packaged upstream programs are diverted with dpkg-divert, so a package reinstall can never put them back over the rebuild. Check the record:

cat /usr/share/doc/cgrates-sac/BUILD_VERSIONS dpkg-divert --list '/usr/bin/cgr-*' | sort

cgrates=v0.10.5 cgrates-commit=0674f9eb51452706095d0b54746666ddd835b902 cgrates-deb=0.10.5-1~deb12u1 go-toolchain=go1.26.9 build-flags=CGO_ENABLED=0 GOOS=linux GOARCH=amd64 -trimpath -buildvcs=false dependency-bumps=golang.org/x/net@v0.60.0 golang.org/x/crypto@v0.57.0 golang.org/x/text@v0.42.0 google.golang.org/grpc@v1.83.2 github.com/rabbitmq/amqp091-go@v1.14.0 go.mod.sha256=5adacaee21bb06efb46211767e2afc03544106e0d7e1ffa8bfb1a63cf0a6dd98 go.sum.sha256=24daddd2f95de37262e18fa0e0de5fdc054f73a95400858dba8667244fa678c9 cgr-engine.sha256=f22a18493f1c415d7e27cf2bde63e1fb12e17196d6fb17df6aef4b3cfe4d9b32 cgr-loader.sha256=6a6e225d09f78729ec9cb0ca553ac8ec50dfa7b956fb7ef6a6d38b502d8b3bd4 cgr-console.sha256=53d2449994dd835f4aca34add1f4c9dea9feace152d1ab4c46c2cdbe1d87d2e5 cgr-migrator.sha256=4445c75b37743d9e9d8b75e12bbb670949dd2ac34020c13ef1d775df4d112fb2 cgr-tester.sha256=b1218e9726627f088cd0d9749c335086a65c828384f0e08b072d5b42ff10166f redis-server=5:7.0.15-1ubuntu0.24.04.5 nginx=1.24.0-2ubuntu7.18 local diversion of /usr/bin/cgr-console to /usr/bin/cgr-console.cgrates-deb local diversion of /usr/bin/cgr-engine to /usr/bin/cgr-engine.cgrates-deb local diversion of /usr/bin/cgr-loader to /usr/bin/cgr-loader.cgrates-deb local diversion of /usr/bin/cgr-migrator to /usr/bin/cgr-migrator.cgrates-deb local diversion of /usr/bin/cgr-tester to /usr/bin/cgr-tester.cgrates-deb

• Basic Auth password: generate a new password and write its hash without putting it on a command line. Then reload nginx, and update cgrates.basicauth.pass in /root/cgrates-credentials.txt and in your applications:

NEW=$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | cut -c1-32) printf '%s\n' "$NEW" | openssl passwd -6 -stdin | sed 's/^/admin:/' | sudo tee /etc/nginx/cgrates.htpasswd >/dev/null
sudo systemctl reload nginx

• Redis password: change requirepass in /etc/redis/redis.conf and data_db.db_password in /etc/cgrates/cgrates.json to the same new value. Update cgrates.redis.pass in the credentials file, then run sudo systemctl restart redis-server cgrates.
• More users: add one user:hash line per user to /etc/nginx/cgrates.htpasswd (hash made the same way) and reload nginx.

The tariff plans, accounts and balances live in Redis logical database 10 (/var/lib/redis). The simplest backup is an EBS snapshot of the root volume. For a point-in-time Redis dump, run SAVE and copy /var/lib/redis/dump.rdb:

sudo bash -c 'REDISCLI_AUTH=$(sed -n "s/^cgrates\.redis\.pass=//p" /root/cgrates-credentials.txt) redis-cli SAVE'
sudo cp /var/lib/redis/dump.rdb <backup-dir>/cgrates-redis-$(date +%F).rdb

Keep your tariff plan CSV files in version control too, because cgr-loader can rebuild the DataDB from them at any time.

Operating system security updates install automatically. Run sudo apt-get update && sudo apt-get upgrade to apply everything else. The cgrates package is held, so an upgrade never replaces the rebuilt programs.

Component Path

Programs (SecureAnyCloud rebuild) /usr/bin/cgr-engine, cgr-loader, cgr-console, cgr-migrator, cgr-tester

Engine configuration /etc/cgrates/cgrates.json (mode 0640)

Service cgrates.service (drop-ins in /etc/systemd/system/cgrates.service.d/)

DataDB Redis 7, logical database 10 (/var/lib/redis)

Sample tariff plans /usr/share/cgrates/tariffplans/

nginx site /etc/nginx/sites-available/sac-cgrates

Basic Auth users /etc/nginx/cgrates.htpasswd (mode 0640)

Certificate and key /etc/ssl/cgrates/

Boot service /usr/local/sbin/cgrates-firstboot.sh

Host name helper /usr/local/sbin/cgrates-set-hostname

Self check /usr/local/sbin/cgrates-credcheck.sh

Credentials /root/cgrates-credentials.txt (mode 0600)

License, source notice and build record /usr/share/doc/cgrates-sac/

• Allow port 22 from your admin network only, and ports 80 and 443 only from the networks your applications call from.
• Use your own DNS name and a certificate that your clients trust (Step 8), and pin it in your applications.
• Give each application its own Basic Auth user (Step 10), and rotate a password if it may have leaked.
• Keep the operating system patched, and snapshot the root volume regularly.