Broadcast Box 2.0.2

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened SRS Streaming Media Server & Media Servers AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• Once the subscription is active, choose Launch your software.
• Choose One-click launch from AWS Marketplace, or Launch from EC2 Console for the full launch wizard. In Version, choose Broadcast Box 2.0.2 on Ubuntu 24.04, then choose your Region.
• Pick an instance type and your key pair. m5.large is recommended, and the software charge is $0.04 per vCPU per hour.
• Configure the security group. The listing's default group opens SSH (22/tcp), HTTP (80/tcp), HTTPS (443/tcp) and WebRTC media (3478/udp). Keep 3478/udp open to everyone who broadcasts or watches, because without it the page loads but the video never plays. Restrict SSH to your own IP address.
• Choose your VPC and a public subnet, or associate an Elastic IP. Leave the metadata defaults, because the image already requires IMDSv2. Then choose Launch.

Option B: AWS CLI

Run this command on your own workstation. Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the VPC, subnet, key pair and CIDRs with your own:

SG=$(aws ec2 create-security-group --group-name broadcast-box \
  --description "Broadcast Box live streaming" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 80 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 443 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol udp --port 3478 --cidr 0.0.0.0/0
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=broadcast-box}]'

You do not need --metadata-options, because the AMI already requires IMDSv2. If you know your viewers' networks, restrict 443 and 3478 to them.

Connect as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

First boot takes a few seconds after the instance starts. It reads the instance's public address and sets the name that Broadcast Box is served as, which is the public DNS name when the instance has one. It creates the TLS certificate, the admin token, the reserved stream and its publish token, and writes /root/broadcast-box-credentials.txt (mode 0600, root).

These are the entries in that file. The tokens and the stream key are not shown here:

sudo grep -E '^(BB_URL|BB_ADMIN_URL|BB_WHIP_URL|BB_WHEP_URL|BB_ICE_ADDRESS)=' /root/broadcast-box-credentials.txt
sudo grep -oE '^[A-Z0-9_]+=' /root/broadcast-box-credentials.txt
sudo stat -c '%a %U:%G %n' /root/broadcast-box-credentials.txt /etc/broadcast-box/secrets.env

BB_URL=https://ec2-18-206-245-254.compute-1.amazonaws.com/ BB_ADMIN_URL=https://ec2-18-206-245-254.compute-1.amazonaws.com/admin BB_WHIP_URL=https://ec2-18-206-245-254.compute-1.amazonaws.com/api/whip BB_WHEP_URL=https://ec2-18-206-245-254.compute-1.amazonaws.com/api/whep BB_ICE_ADDRESS=18.206.245.254 BB_URL= BB_ADMIN_URL= BB_ADMIN_TOKEN= <set-at-first-boot>= BB_PUBLISH_TOKEN= <set-at-first-boot>= BB_WHEP_URL= BB_PLAYER_URL= BB_CERT_SHA256= BB_ICE_ADDRESS= 600 root:root /root/broadcast-box-credentials.txt 640 root:broadcastbox /etc/broadcast-box/secrets.env

Value What it is for

BB_URL The address of this instance's Broadcast Box

BB_PUBLISH_TOKEN The bearer token that lets you broadcast to the reserved stream (keep it secret)

BB_STREAM_KEY The key viewers use to watch the reserved stream

BB_PLAYER_URL The player link for the reserved stream (BB_URL followed by the stream key): share it with your viewers

BB_WHIP_URL The WHIP endpoint you broadcast to

BB_ADMIN_TOKEN The token for the admin portal at BB_ADMIN_URL (keep it secret)

BB_CERT_SHA256 The fingerprint of this instance's certificate, to check the browser warning against

BB_ICE_ADDRESS The address advertised for WebRTC media (UDP 3478)

To read the tokens, run sudo cat /root/broadcast-box-credentials.txt in your own session. Store them in your password manager.

Check that the network-configuration unit has run and first boot has finished. The server and nginx should be active. Broadcast Box listens on 127.0.0.1:8080 and on UDP 3478 on the instance's own addresses, and only sshd and nginx listen on TCP beyond loopback:

systemctl is-active broadcast-box-netconf.service broadcast-box.service nginx.service ls /var/lib/sac/data/broadcast-box-firstboot.done
sudo ss -Htlnp | awk '{print $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort -u sudo ss -Hulnp | grep -F '"broadcast-box"' | awk '{print $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort -u sudo cat /run/broadcast-box/ice.env
sudo sed -n '/^tag commit/p;/^binary sha256/p;/^govulncheck/p' /usr/share/doc/broadcast-box/BUILD-PROVENANCE.txt

active active active /var/lib/sac/data/broadcast-box-firstboot.done 0.0.0.0:22 users:(("sshd"),("systemd")) 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) 127.0.0.1:8080 users:(("broadcast-box")) 127.0.0.53%lo:53 users:(("systemd-resolve")) 127.0.0.54:53 users:(("systemd-resolve")) [::]:22 users:(("sshd"),("systemd")) [::]:443 users:(("nginx"),("nginx"),("nginx")) [::]:80 users:(("nginx"),("nginx"),("nginx")) 172.31.87.188:3478 users:(("broadcast-box")) [fe80::10ff:fbff:fe69:9877]%ens5:3478 users:(("broadcast-box")) NAT_1_TO_1_IP=18.206.245.254 tag commit 60601cd86b2c84d577b51560135358e7156aa77e binary sha256 0ea948ea9d4002b019921fe442b2d9f7d0fee9c164bcfedc2ddd61748463b7be (reproducible) govulncheck v1.9.0 -mode=binary: No vulnerabilities found.

NAT_1_TO_1_IP is the public address that Broadcast Box tells broadcasters and viewers to send media to. It is read again on every boot, so a stop and start that gives the instance a new public address keeps working.

These commands show that the web app answers over a verified TLS connection and the admin API refuses a request without a token. They also show that an anonymous or wrongly authenticated broadcast is refused, plain HTTP redirects to HTTPS, and an unknown Host header gets no answer.

The last command is the image's own end-to-end check, which signs in with the instance's own tokens:

H=$(sed -n 's/^set \$bb_host "\(.*\)";$/\1/p' /etc/nginx/broadcast-box-host.conf) C=(--connect-to ::127.0.0.1: --cacert /etc/nginx/tls/broadcast-box.crt) curl -s "${C[@]}" -o /dev/null -w 'web app -> %{http_code}\n' "https://$H/" curl -s "${C[@]}" -o /dev/null -w 'admin API, no token -> %{http_code}\n' -X POST "https://$H/api/admin/login" curl -s "${C[@]}" -w ' <- WHIP publish, no token: %{http_code}\n' -X POST -H 'Content-Type: application/sdp' --data-binary 'v=0' "https://$H/api/whip" curl -s "${C[@]}" -o /dev/null -w 'WHIP publish, wrong token -> %{http_code}\n' -X POST -H 'Authorization: Bearer not-a-token' -H 'Content-Type: application/sdp' --data-binary 'v=0' "https://$H/api/whip" curl -s --connect-to ::127.0.0.1: -o /dev/null -w 'http -> %{http_code} %{redirect_url}\n' "http://$H/" curl -sk -o /dev/null -w 'unknown Host -> %{http_code}\n' -H 'Host: evil.example' https://127.0.0.1/ || true
sudo broadcast-box-selftest | tail -4

web app -> 200 admin API, no token -> 401 Authorization was not set <- WHIP publish, no token: 400 WHIP publish, wrong token -> 401 http -> 301 https://ec2-18-206-245-254.compute-1.amazonaws.com/ unknown Host -> 000 selftest: ok app TCP listener 127.0.0.1:8080 only selftest: ok app UDP listener(s) on port 3478 only selftest: ok broadcast-box-netconf.service ran this boot selftest: BROADCAST-BOX-SELFTEST OK

--connect-to ::127.0.0.1: sends each request to this instance while keeping the real host name in the request, exactly as a browser sends it. 000 means the server closed the connection without an answer.

Browse to BB_URL (https://<public-dns-name>/). The certificate is self-signed, so your browser warns you once. Check the fingerprint against BB_CERT_SHA256 and accept the certificate for this host, or install your own certificate (Step 8).

To watch, choose I want to watch, paste the stream key BB_STREAM_KEY and choose Join stream. Alternatively, open BB_PLAYER_URL directly. While someone is broadcasting, the player starts within a second:

From OBS Studio (30 or later): open Settings, Stream, set Service to WHIP, Server to BB_WHIP_URL and Bearer Token to BB_PUBLISH_TOKEN, then choose Start Streaming.

OBS checks the server's certificate against the certificates your workstation trusts. Either serve Broadcast Box under your own name with a trusted certificate (Step 8), or add this instance's certificate (/etc/nginx/tls/broadcast-box.crt) to your workstation's trusted certificates. It is an end-entity certificate for this server's names only, so trusting it does not let it vouch for any other site.

For low latency, set Keyframe Interval to 1 or 2 seconds and use H.264 with no B-frames.

From a browser: on BB_URL choose I want to stream, paste the publish token BB_PUBLISH_TOKEN into the key field and choose Start stream. Then choose Publish Webcam (or Publish Screen/Window/Tab) and allow the camera and microphone. The broadcast appears to viewers under the stream key, never under the token.

The confirmation banner offers a watch link built from the page address, which contains your publish token. Do not share that link. Share BB_PLAYER_URL instead.

From other WHIP encoders: any encoder that runs full ICE works the same way (GStreamer's whipclientsink, the libdatachannel and pion WHIP clients). ffmpeg's built-in WHIP muxer is an exception. It connects only to the first address in the server's answer, which is the instance's private address, so it can publish only from inside the same VPC or over a VPN. From the internet, use OBS, a browser or a full-ICE client.

When SecureAnyCloud built this image, a WHIP publisher and a WHEP viewer on a workstation in London broadcast an H.264 test pattern to an instance in us-east-1, so every packet crossed the Atlantic twice. The one-way delay from the moment the publisher sent a video packet to the moment the viewer received it was 110 ms at the median and 116 ms at the 95th percentile, and every received frame was decodable.

WebRTC media does not travel over the web connection. Broadcasters and viewers send it to the address that the server advertises, on UDP 3478. Two things must be true:

• The security group allows 3478/udp from everyone who broadcasts or watches. Opening 443 alone gives a page that loads and a player that never plays.
• The advertised address is reachable. On every boot, broadcast-box-netconf.service reads the instance's public IPv4 address from instance metadata and writes it to /run/broadcast-box/ice.env. An instance with no public address advertises its private address, so media then works only inside the VPC or over a VPN.

sudo journalctl -u broadcast-box-netconf.service -b --no-pager -o cat | grep 'broadcast-box-netconf:'

broadcast-box-netconf: WebRTC media address 18.206.245.254:3478/udp (instance metadata public-ipv4) broadcast-box-netconf: served as https://ec2-18-206-245-254.compute-1.amazonaws.com/ (instance metadata)

Sometimes the address that viewers should use is not the instance's own public address, for example an Elastic IP that you move between instances, or a Network Load Balancer that passes UDP 3478 through. In that case, write the address to /etc/sac/broadcast-box-public-ip and restart the two units:

echo 203.0.113.10 | sudo tee /etc/sac/broadcast-box-public-ip
sudo systemctl restart broadcast-box-netconf.service broadcast-box.service

Some corporate networks block outbound UDP. Broadcast Box can also carry media over TCP (TCP_MUX_ADDRESS in /etc/broadcast-box/broadcast-box.env, for example TCP_MUX_ADDRESS=0.0.0.0:3478). It is off in this image because it opens another port.

If you turn it on, add that TCP port to the security group. Also add it to the SocketBindAllow= lines with sudo systemctl edit broadcast-box.service.

Point a DNS record (for example live.example.com) at the instance's public or Elastic IP address, then tell the image to serve that name. The command creates a new self-signed certificate for the name, pins nginx to it, updates the URLs in the credentials file and keeps the name across reboots:

sudo broadcast-box-set-hostname live.example.com

For a certificate that browsers and OBS trust without a warning, obtain one for that name. For example, use certbot's certonly mode with its own temporary web server, or request one from your organization's CA.

Copy the certificate chain and key over /etc/nginx/tls/broadcast-box.crt and /etc/nginx/tls/broadcast-box.key (key mode 0600, root). Then run sudo systemctl reload nginx.

Open BB_ADMIN_URL and sign in with BB_ADMIN_TOKEN. The portal shows who is broadcasting and watching, and it manages the reserved streams. You can add a stream for another broadcaster (each gets its own key and token), reset a stream's token, or remove a stream.

The browser keeps the admin token in its local storage and sends it with each request. Sign out on shared computers.

• New admin token: sudo broadcast-box-rotate-admin-token writes a new token to the credentials file and restarts the server; the old token stops working.
• New publish token for the reserved stream: use Reset token in the admin portal. The credentials file still shows the old token; remove it once you have stored the new one.
• List a stream publicly: a broadcaster can mark their stream public with their own publish token (/api/whip/profile), or the admin can do it from the portal; public streams appear under Current streams on the home page.

You can check the security controls behind these defaults at any time:

systemctl show -p IPAddressDeny broadcast-box.service broadcast-box-firstboot.service nginx.service
systemctl show -p User -p CapabilityBoundingSet -p SocketBindAllow -p SocketBindDeny broadcast-box.service
sudo grep -E '^(STREAM_PROFILE_POLICY|HTTP_ADDRESS|UDP_MUX_PORT)=' /etc/broadcast-box/broadcast-box.env openssl x509 -in /etc/nginx/tls/broadcast-box.crt -noout -ext basicConstraints,keyUsage
sudo sshd -T | grep -E '^(permitrootlogin|passwordauthentication|x11forwarding) '

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 SocketBindAllow=udp3478 SocketBindAllow=tcp8080 SocketBindDeny=any CapabilityBoundingSet= User=broadcastbox HTTP_ADDRESS=127.0.0.1:8080 UDP_MUX_PORT=3478 STREAM_PROFILE_POLICY=RESERVED X509v3 Basic Constraints: critical CA:FALSE X509v3 Key Usage: critical Digital Signature, Key Encipherment permitrootlogin no passwordauthentication no x11forwarding no