Untitled :: OliveTin Docs

Support & Troubleshooting

Where to find help

Please feel free to open a support request issue on GitHub to ask for help with troubleshooting, or come and chat with us.

inline Open a support request

inline Chat on Discord

sosreport

OliveTin has a useful feature to gather information about your installation that is useful when you’re asking for help - when you have a support request. If you are able to provide sosreport, this generally helps others help you a lot. The sosreport feature does NOT send any information to the developers or anybody else, it’s simply text - copy and paste it to where someone is trying to help you!

Example SOS Report

### SOSREPORT START (copy all text to SOSREPORT END)
# Build:
commit: nocommit
version: dev
date: nodate

# Runtime:
os: linux
osreleaseprettyname: PRETTY_NAME="Fedora Linux 37 (Workstation Edition)"
arch: amd64
incontainer: false
lastbrowseruseragent: ""

# Config:
countofactions: 7
loglevel: INFO

### SOSREPORT END  (copy all text from SOSREPORT START)

You can then copy and paste this text into a GitHub issue, discussion, Discord chat, or wherever else someone might be helping you.

How do I generate a sosreport?

OliveTin needs to be able to startup and it’s API needs to be functional. Once OliveTin is started, simply browse to: http://myserver:1337/api/sosreport

Optional: Allow insecure (but easy) dumping of SOS Reports to the browser

There is a configuration option you can set in your config.yaml that allows you to easily dump SOS Reports to your browser when visiting the API. This is turned off by default, as you should not allow anybody to request a sosreport at any time that they like, but you can enable this option temporarily to easily get access to the SOS Report.

config.yaml

InsecureAllowDumpSos: true

Default: SOS Report dump to logs

You should get a simple JSON message saying something like;

alert: "Your SOS Report has been logged to OliveTin logs."

If you see this, great! The actual contents of the sosreport are not returned to your browser for security reasons (guests could get info about your installation, etc).

To find the sosreport depends on how you are running OliveTin, if you are running in a container, then try docker logs olivetin (where "olivetin" is your container name). If you are running using systemd, then try journalctl -eu OliveTin.

What if I cannot even get to the OliveTin API?

OliveTin’s web interface doesn’t need to be working to get a sosreport (as the web interface and the API are separate). However, if OliveTin won’t even startup, or you cannot seem to get to the API, then sadly a sosreport can’t help you. Please do specify that when you ask for help.

Exit code 127

Exit code 127 on Linux typically means "command not found". This can be the case when you need to install command in a container image for example.

PUID and PGID support

The OliveTin container image does not use the PUID and PGID convention to specify which user the container should run as - this is a convention that was popularized by linuxserver.io, because their container images use supervisord. Instead, simply use the --user argument when defining the container, to change the user OliveTin runs as.

LSIO documentation for PUID and PGID, that says that --user is the same thing

An example is shown below;

Using --user

user@host: docker create --name olivetin -p 1337:1337 -v /etc/OliveTin/:/config:ro docker.io/jamesread/olivetin --user container:container
user@host: docker start olivetin

Error Getting Buttons

This is most often caused by not being able to get to /api/ properly - normally due to a bad proxy config, or your network was disconnected.

Error Connecting to WebSocket

If OliveTin was working, but this error popped up, it’s most likely because your reverse proxy closed the connection due to a timeout.

If OliveTin is always displaying this error, it’s probably your reverse proxy not handling the websocket properly. Please check the Reverse Proxy documentation for more information.

Error Fetching WebUI Settings

This is a less common issue, but it means that the main web HTML has loaded, but it could not get http://yourserver:1337/webUiSettings.json - most likely because of a 404 (Not Found) or JSON parse issue. You can see the exact reason if your browser as Web Developer Tools - look in the console. Firefox and Chrome both have great web developer tools, that can normally be opened with the F12 key, or from the developer tools menu.

The most common cause of this issue is a broken reverse proxy configuration. To debug this, browse to http://yourserver:1337/webUiSettings.json and adjust your reverse proxy configuration until the file loads properly. See [reverse-proxies] for common configuration instructions.

An uncommon cause of this issue is if you are self-hosting the HTML outside of OliveTin. This is supported, but it means you will need to write the webUiSettings.json file manually. This is currently not documented as very very few people really need or want to do this. It’s very uncommon at the moment to self host the HTML outside of the OliveTin main server. Jump on the discord to discuss this if you want to do this, see Where to find help.

Error: JS Modules not supported

This is most likely because you are using a very old browser, or have some Javascript disabled.

This page describes the compatible browsers for Javascript modules; https://caniuse.com/es6-module .

There is no workaround for this apart from updating your browser / using a better browser, as OliveTin wants to be a progressive web app and doesn’t intend to support browsers without module support.

Advanced Troubleshooting

Sometimes you need to really see what OliveTin is doing, especially when debugging entities. OliveTin has several built-in options for advanced troubleshooting, but enabling these output options can expose sensitive information, so they can be insecure.

OliveTin itself is not "insecure" by using these options, they would not let attackers execute different commands or anything like that. It’s just that using these options can expose data (like entity files) that maybe you don’t want an attacker to see.

All these configuration options are false by default, and should be deleted from the config or reset back to false when you are not using them.

Dump SOS Reports

InsecureAllowDumpSos: true - will allow dumping SOS Reports as plain text when visiting http://server:1337/api/sosreport

Dump Action Map

InsecureAllowDumpActionMap: true - will allow dumping all the actions (and those generated with entities) and their public IDs, eg: http://server:1337/api/DumpActionMap

Dump Vars

InsecureAllowDumpVars: true - will allow dumping all the "string variables" from a map that is mainly used for entities, eg: http://server:1337/api/DumpVars

Dump JWT Claims

InsecureAllowDumpJwtClaims: true - will dump all the claims from a successfully parsed JWT token. This can be useful when trying to see how OliveTin is parsing the token, and what key fields are available.

Debug Log Options

logDebugOptions:
    singleFrontendRequests: true
    singleFrontendRequestHeaders: true
    aclMatched: true
    aclNotMatched: true