OpenSim Regions

Installing an OSgrid Region on a Linux Server

Introduction – Read This Before You Start

This guide walks you through installing a single region hosted on OSgrid onto a Linux server, from an empty folder to a running, backed-up region that anyone can teleport to. It is written from real experience – this is the exact sequence that worked for us when we built a region, with the genuine problems we hit flagged clearly so they do not catch you out the way they caught us.

Before you begin, one assumption. This guide assumes you already have a server up and running with Ubuntu installed, and that you have root SSH access to it. Setting up the VPS itself, installing the operating system, and securing it are outside the scope of this guide – we pick up from the point where you can log into a working Ubuntu server.

A word on who this is for. This guide assumes you are comfortable in a Linux terminal – typing commands into a black screen, editing config files, and reading error messages carefully. You do not need to be a professional systems administrator, but you do need to be patient, methodical, and willing to read each step before you act on it. If the command line makes you anxious, get someone more technical to sit with you, because a lot of this is precise work where a wrong port or a missed setting means the region simply will not start.

That said – if you are reasonably technically minded and prepared to take your time, this is absolutely achievable. Everything below is covered in detail, including the parts that go wrong and why.

What Made It Work – Reference Values

These are the real values from the working build. Yours will differ where noted, but this is the shape of what you are aiming for:

Setting	Value
Folder	/root/osgrid/ (self-contained; sim runs from bin/)
Port	9001 (OpenSim’s default is 9000)
Database	osgrid (a dedicated MySQL database)
DB user	osgrid@localhost (scoped to the osgrid db only)
Runtime	.NET 8 (dotnet) – NOT Mono; OSgrid needs .NET 8
Screen session	osgrid
External host	the server’s public IP
OSgrid avatar	your OSgrid account name (the estate owner must match it)

Prerequisites – Confirm These Before You Start

Have all of the following in hand before you type a single command. Chasing any of these down halfway through is a needless interruption:

• A server already up and running with Ubuntu installed.
• An OSgrid account already created (avatar name and password).
• Root SSH access to the server (PuTTY and your key).
• The public IP of the server.
• A free port for the region. OpenSim defaults to 9000; this guide uses 9001, but any free port works as long as you use it consistently throughout.
• An open coordinate on the OSgrid map for the region location.

Step 1 – Check or Install .NET 8

OSgrid’s current builds require the .NET 8 runtime specifically. This matters more than it sounds: .NET 7 or .NET 9 will not do – the region will crash at boot. Check what is already present on the server with:

dotnet --list-runtimes

You want to see both of these listed:

Microsoft.NETCore.App 8.x
Microsoft.AspNetCore.App 8.x

If they are missing, install .NET 8. On Ubuntu 24.04 it is in the default repositories, so this is straightforward. If you happen to have Mono installed for anything else, do not worry – .NET 8 sits alongside it happily and the two do not interfere.

Step 2 – Create the Folder and Download the Build

Make the self-contained folder that will hold everything:

mkdir -p /root/osgrid

Now get the current build link from OSgrid’s official download page: https://www.osgrid.org/download.php

Open that page in a browser. The page sits behind Cloudflare, which means fetching it from the command line just returns an anti-bot holding page rather than the real link. Copy the current Linux .zip link from the browser.

Gotcha – Cloudflare 403 on wget. The download host itself (download.osgrid.org) is also behind Cloudflare, and it rejects wget’s default user-agent with a flat “403 Forbidden”. The fix is to send a browser user-agent so the request looks like it came from a real browser. This is the exact command that worked for us:

cd /root/osgrid && wget --user-agent="Mozilla/5.0 (X11; Linux x86_64) \
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36" \
--referer="https://www.osgrid.org/download.php" \
<PASTE-CURRENT-ZIP-URL-HERE>

If wget still throws a 403 no matter what, do not fight it – download the zip in your browser and upload it to /root/osgrid/ using FileZilla over SFTP instead.

Either way, verify the download actually completed. The file size should match the size shown on the download page, not a few kilobytes. A tiny file means wget grabbed an error page rather than the build:

ls -lh /root/osgrid/

Step 3 – Extract the Build

Before unpacking, peek inside the archive to confirm it extracts cleanly to a version.txt file and a bin/ folder, rather than spilling thousands of loose files into your current directory:

unzip -l /root/osgrid/<build>.zip | head -30

Then extract it quietly. The -q flag matters here – the archive contains thousands of asset files, and without it your terminal will scroll for a very long time:

cd /root/osgrid && unzip -q <build>.zip

Confirm the layout. /root/osgrid/ should now contain version.txt, bin/, and optional/:

ls -lh /root/osgrid/

From here on, the simulator runs from /root/osgrid/bin/.

Step 4 – Create the Database and User

The region needs its own MySQL database and a dedicated database user to go with it. Enter MySQL as root:

mysql -u root -p

Then run the following, replacing CHANGE_ME with a fresh password for this database user (not a password you use anywhere else):

CREATE DATABASE osgrid CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'osgrid'@'localhost' IDENTIFIED WITH mysql_native_password BY 'CHANGE_ME';
GRANT ALL PRIVILEGES ON osgrid.* TO 'osgrid'@'localhost';
FLUSH PRIVILEGES;

Now verify. You should see the osgrid database in the list, and the osgrid user scoped to localhost:

SHOW DATABASES;
SELECT user, host FROM mysql.user WHERE user = 'osgrid';
EXIT;

A few lessons worth carrying over from this step:

• Use mysql_native_password authentication. OpenSim needs it, and a newer default auth plugin will cause connection failures.
• SslMode=None belongs in the connection string, which you will set in the next step.
• The osgrid user is granted rights only on the osgrid database. This is good practice – the account is scoped to exactly what it needs and nothing more.

Step 5 – Point the Build at the Database

The file to edit is /root/osgrid/bin/config-include/GridCommon.ini. Back it up first, every time, before you touch it:

cd /root/osgrid/bin/config-include
cp GridCommon.ini GridCommon.ini.backup

Find the MySQL lines. By default they are commented out:

grep -n -iE 'StorageProvider|ConnectionString' GridCommon.ini

Uncomment those two lines and set them to point at the osgrid database. These are the working values:

StorageProvider = "OpenSim.Data.MySQL.dll"
ConnectionString = "Data Source=localhost;Database=osgrid;User ID=osgrid;Password=CHANGE_ME;Old Guids=true;SslMode=None;"

Leave the MSSQL, PGSQL, and EstateConnectionString lines commented out – you do not need them.

Verify your edit. Both lines should be uncommented and pointing at Database=osgrid:

grep -n -A1 'StorageProvider\|ConnectionString' GridCommon.ini | head -8

One important note. The OSgrid build arrives preconfigured to talk to OSgrid’s own services – login, asset, grid, and the rest all point at *.osgrid.org already. You are only setting the database here. Do not change the service URLs. That is what keeps your region connected to OSgrid rather than trying to be its own grid.

Step 6 – Set the HTTP Listener Port (the Crash-Fixer)

Here is the one that will bite you if you are not ready for it. The region wizard you are about to run sets the region’s UDP port, but the HTTP listener port is a completely separate setting that lives in OpenSim.ini, and it defaults to 9000. If you are running your region on any other port, this must be set to match, or the two halves of the region end up split across two different ports. And if the port it tries to bind is already occupied by something else on the server, the very first boot crashes with a blunt message:

[BASE HTTP SERVER]: Error - Address already in use

The fix is simple once you know to look for it. Back up the file, then find the listener port setting:

cd /root/osgrid/bin
cp OpenSim.ini OpenSim.ini.backup
grep -n -i 'http_listener_port' OpenSim.ini

Uncomment it and set it to your region port, 9001:

http_listener_port = 9001

Verify it is uncommented and reads 9001:

grep -n -i 'http_listener_port' OpenSim.ini

The thing to understand is that both ports move to 9001 – the UDP port (which you set through the wizard in the next step) and the TCP/HTTP listener port (which you just set here by hand). Miss this second one and the first boot will not survive.

Step 7 – Open the Firewall (Both Layers)

Port 9001 needs both TCP and UDP open, and it needs them open in two places. This trips people up constantly, because a port can look perfectly open on the box while still being blocked further out.

First layer – the provider’s external firewall panel (for us this was IONOS). Add TCP 9001 (UDP may already be covered by an existing range).

Second layer – the box’s own firewall, ufw. Check whether it is even active:

ufw status

If it reports “inactive”, then the provider panel is the only gate and you are done. If it reports “active”, add the port:

ufw allow 9001

Gotcha – always check both layers. A port that appears open on the box can still be blocked at the provider, and vice versa. On a VPS the public IP is usually direct with no NAT in front of it, which is why ExternalHostName is set to the public IP rather than an internal address.

Step 8 – First Boot and the Region Wizard

Start the simulator attached, so you can see and answer the setup prompts:

cd /root/osgrid/bin
dotnet OpenSim.dll

Expect a great deal of startup text scrolling past. Some of it will be red, and that is normal – red does not automatically mean failure here. After the startup, it asks you a series of region questions. Answer them with your values:

Prompt	What to enter
New region name	your region name (UNIQUE on OSgrid – see gotcha)
Region UUID	press Enter (accept the generated one)
Region Location	your open map coord, e.g. XXXX,YYYY (NOT 1000,1000)
Internal IP [0.0.0.0]	press Enter
Internal port [9000]	type 9001 – do NOT accept the default
Allow alternate ports	press Enter
Resolve hostname (Docker)	press Enter (False)
External host name	your public IP
Join existing estate?	press Enter (no)
New estate name	your estate name
Estate owner first name	your OSgrid avatar FIRST name
Estate owner last name	your OSgrid avatar LAST name

Gotcha – “Duplicate region name”. Region names on OSgrid are global, shared across the entire grid. If the name you chose is already taken, registration fails with “Duplicate region name”. The fix is simply to pick a distinct name. You can change it afterwards without re-running the entire wizard by editing the section header in /root/osgrid/bin/Regions/Regions.ini – for example, change [OldName] to [New Name]. If a sed command with anchors refuses to match, the cause is almost always Windows line endings in the file – use an anchor-free replace instead:

sed -i 's|\[OldName\]|[New Name]|' Regions/Regions.ini

Then relaunch.

Success looks like this:

INITIALIZATION COMPLETE FOR <region> - LOGINS ENABLED
Region (<region>) #        <- a responsive console prompt

Confirm it with show regions – it should list the region, Ready? Yes, on port 9001.

Step 9 – Test From a Viewer

Now prove it works end to end. In Firestorm, select or add OSgrid using the login URI http://login.osgrid.org/. Log in with your OSgrid avatar, open the World Map, search for your region name, and teleport to it. If you arrive, the port is reachable all the way through – provider firewall, box firewall, and simulator. While you are testing like this with the sim running attached, keep PuTTY open; the moment you close it, the sim stops.

Step 10 – Run It Detached (Survives Logout)

Testing attached is fine, but you do not want the region to die the instant you disconnect. Stop the attached instance cleanly first – at the Region ( ) # prompt, type quit. Wait for the shell prompt to return, then relaunch it detached inside a screen session so it keeps running after you log out:

cd /root/osgrid/bin && screen -dmS osgrid dotnet OpenSim.dll

From then on, you manage it like this:

Action	Command
List sessions	screen -ls
Enter the console	screen -r osgrid
Leave it running	close the PuTTY window, or from another shell: screen -d osgrid
Stop cleanly	screen -r osgrid, then type quit
Force-stop if hung	screen -S osgrid -X quit

One practical note. The “official” way to detach is Ctrl-A then D, but over PuTTY that keystroke often does not register. In practice, simply closing the PuTTY window detaches the session without stopping the sim, which works reliably.

Step 11 – The Watchdog (Auto-Restart on Crash or Hang)

This step is strongly recommended. A fresh OSgrid region can hang – the process stays alive but stops responding – after a hiccup on the wider grid. A watchdog that probes the port catches both cases: a process that has died outright, and one that is technically alive but no longer answering. The script lives inside /root/osgrid/. Create /root/osgrid/watchdog.sh with this content:

#!/bin/bash
PORT=9001
SESSION=osgrid
BINDIR=/root/osgrid/bin
LOG=/root/osgrid/watchdog.log
if nc -z -w 5 127.0.0.1 "$PORT" >/dev/null 2>&1; then
    exit 0
fi
echo "$(date '+%Y-%m-%d %H:%M:%S') - port $PORT not responding, restarting $SESSION" >> "$LOG"
screen -S "$SESSION" -X quit >/dev/null 2>&1
sleep 3
cd "$BINDIR" && screen -dmS "$SESSION" dotnet OpenSim.dll
echo "$(date '+%Y-%m-%d %H:%M:%S') - relaunched $SESSION" >> "$LOG"

Make it executable:

chmod +x /root/osgrid/watchdog.sh

Test it while the region is healthy. It should do nothing and exit cleanly with 0:

/root/osgrid/watchdog.sh; echo "exit: $?"

Now schedule it to run every 5 minutes, taking care not to wipe out any cron lines you already have. This one-liner appends to your existing crontab rather than replacing it:

(crontab -l; echo "*/5 * * * * /root/osgrid/watchdog.sh >> /root/osgrid/watchdog.log 2>&1") | crontab -
crontab -l          (confirm your existing lines plus the new one)

Check on it whenever you like:

cat /root/osgrid/watchdog.log

An occasional restart in that log is perfectly normal. Frequent restarts are a signal that something deeper is worth investigating.

Step 12 – Backups

Do not skip this, and do not put it off. OSgrid does not guarantee asset retention, and a region that has been shut down can be purged from the map entirely. The safety of your content is your own responsibility.

Make a backups folder inside the install:

mkdir -p /root/osgrid/backups

The OAR file captures your region’s contents – terrain, objects, and builds. Take it with no other avatars on the region, because saving a large OAR places real load on the server. At the Region ( ) # console:

save oar /root/osgrid/backups/<region>-YYYYMMDD.oar

Wait for the message “Finished writing out OAR”, then verify the file actually has size to it:

ls -lh /root/osgrid/backups/

Warnings about missing or duplicate asset references during the save are normal and harmless – do not let them alarm you.

It is also worth capturing a small config bundle, which saves you re-doing the whole setup if you ever need to rebuild. From a shell:

tar -czf /root/osgrid/backups/<region>-config-YYYYMMDD.tar.gz \
  -C /root/osgrid bin/config-include/GridCommon.ini bin/OpenSim.ini \
  bin/Regions/Regions.ini watchdog.sh

Then pull both files off the server using FileZilla over SFTP, down to your own PC. A backup that lives only on the server you are trying to protect is no backup at all – if the server is lost, so is the backup.

One thing you do not need to back up separately is the osgrid MySQL database. The OAR already captures the region’s meaningful contents, and OSgrid holds your account, inventory, and assets on the grid side. Between the OAR and the config bundle, you have what you need to rebuild.

Problem Checklist – The Things That Actually Bit Us

• .NET 8 specifically (not 7 or 9), or it crashes at boot.
• The download page and file host are both behind Cloudflare – use a browser for the link, a browser user-agent for wget, or FileZilla the zip up by hand.
• http_listener_port in OpenSim.ini defaults to 9000 – set it to match your chosen region port so both halves line up (and if that port is already taken, boot fails “Address already in use”).
• The wizard’s Internal port prompt also defaults to 9000 – type your port, do not accept it.
• Region names are global on OSgrid – “Duplicate region name” means pick another.
• The firewall is two layers (provider panel plus ufw) – open both.
• Regions.ini may have Windows line endings – use an anchor-free sed.
• Ctrl-A D detach may not register over PuTTY – close the window to detach instead.
• Take OARs with no visitors logged in; a region shutdown can purge it from OSgrid.

Quick Reference – Day to Day

Task	Command
Start detached	cd /root/osgrid/bin && screen -dmS osgrid dotnet OpenSim.dll
Enter console	screen -r osgrid
List sessions	screen -ls
Stop cleanly	screen -r osgrid, then quit
Force stop	screen -S osgrid -X quit
Watchdog log	cat /root/osgrid/watchdog.log
Take an OAR	(console) save oar /root/osgrid/backups/<region>-YYYYMMDD.oar

Take your time, read before you type, and when something goes wrong read the actual error message before you start changing things – it almost always tells you exactly what is wrong. Good luck with your region.