The short answer
Upload .cs plugin files to oxide/plugins. Their settings appear in
oxide/config after the first run. Use oxide.reload PluginName to
apply changes without restarting, and grant permissions to groups with
oxide.grant group (GROUP) (PERMISSION) rather than to individuals.
Key points
- Three folders: plugins, config, data. Each has one job.
- Config files only appear after the plugin has run once. Do not create them by hand.
oxide.reloadbeats restarting for almost every plugin change.- Grant to groups, not people. It scales and it is auditable.
- Every plugin's own documentation lists its permissions. Read it before guessing.
The three folders
uMod creates three folders on your server, and knowing which does what saves a lot of confusion later.
oxide/plugins- The plugin files themselves, as
.cs. Dropping a file in here loads it automatically. oxide/config- Configuration files for most plugins. These are generated by the plugin on first run, not supplied by you.
oxide/data- Stored data some plugins keep between restarts, such as player records or economy balances. Treat this as the plugin's memory rather than something to edit casually.
A missing config file is not a problem to fix. If you have just uploaded a plugin and
oxide/config has nothing for it, that is because the plugin has not run yet.
Start the server, let it load, and the file will be there.
Uploading plugins
-
Get the plugin file
Download the
.csfile from the uMod plugin library or wherever the author distributes it. -
Upload it to oxide/plugins
Through the file manager or over FTP. Upload the
.csfile itself, not a zip of it. -
Let it load
uMod picks up new files automatically. Watch the console for a load confirmation or an error.
-
Configure it
Its config file will now exist in
oxide/config. Edit it, then runoxide.reload PluginNameto apply.
Every plugin on the uMod website comes with a description covering its setup, its configuration options and the permissions it defines. Read that page before you start guessing at settings, because most of the questions you are about to have are answered on it.
The commands you need
| Command | What it does |
|---|---|
oxide.reload (PLUGIN NAME) | Reloads the specified plugin. |
oxide.unload (PLUGIN NAME) | Unloads the specified plugin. |
oxide.reload * | Reloads all plugins at once. |
oxide.usergroup add (GROUP NAME) | Creates a new Oxide user group. |
oxide.grant group (GROUP NAME) (PERMISSION) | Grants a permission to a group. |
oxide.grant user (USERNAME/STEAM64 ID) (PERMISSION) | Grants a permission to a single user. |
oxide.reload is the one that changes how you work. Editing a config and reloading
a single plugin takes seconds and does not disconnect anybody. Restarting the server to achieve
the same thing costs your players a map load and, if the seed changed, up to ten minutes.
Permission groups in practice
Oxide permissions can be granted to an individual user or to a group. Both work. Use groups.
The reason is maintenance. Grant ten permissions directly to five VIPs and you have fifty
grants to track, and when someone stops being a VIP you have to remember all ten. Grant the ten
permissions to a VIPs group and adding or removing a person is one command.
-
Create the group
oxide.usergroup add VIPs -
Grant the group its permissions
oxide.grant group VIPs kits.vip -
Add people to the group
Rather than granting them permissions individually. Their access then follows the group definition.
Worked examples
- Reload a plugin you just updated
- You replaced the BetterChat file, so run
oxide.reload BetterChat. No restart needed. - Give admins noclip
oxide.grant group Admins noclip.usegives everyone in the Admins group that permission.- Create a VIP tier
oxide.usergroup add VIPs, then grant it whatever the paid tier should include.- Grant one person something temporarily
oxide.grant user 76561198000000000 kits.event. Use this sparingly, and remember you granted it.- Turn a misbehaving plugin off right now
oxide.unload PluginName. Faster and less disruptive than a restart, and it tells you immediately whether that plugin was the problem.
Habits worth having
- Back up before you change plugins
- Take a copy of
oxide/before adding or removing anything. Restoring a folder is quicker than reconstructing a configuration from memory. - Add one plugin at a time
- Add, reload, watch the console and the server FPS, then move on. Adding six at once and finding the server unhappy leaves you with six suspects.
- Watch performance as you go
- Plugins are the main influence on Rust server performance, and a plugin that looks trivial can still cost you every tick.
- Keep plugins updated
- Check uMod after each Rust update. An out-of-date plugin fails compilation and the error names it, which is at least easy to diagnose.
- Read the console
- uMod is unusually good at telling you what went wrong. Most plugin problems are already explained in the output you have not scrolled up to read.
For more depth on the framework itself, the official uMod documentation is the authoritative source. If you have not installed it yet, start with our guide on installing uMod on a Rust server.