Repository files navigation

A process manager with an HTTP API for remote console and file access.

Octyne allows running multiple apps on a remote server and provides an HTTP API to manage them. This allows for hosting web servers, game servers, bots and so on on remote servers without having to mess with SSH, usingscreen andsystemd whenever you want to make any change, in a highly manageable and secure way.

It incorporates the ability to manage files and access the terminal output and input over HTTP remotely. For further security, it is recommended to use HTTPS (seeconfig.json) to ensure end-to-end secure transmission.

retrixe/ecthelion complements octyne by providing a web interface to control apps on octyne remotely.

• Download the latest version of Octyne from GitHub Releases for your OS and CPU. Alternatively, you can get the latest bleeding edge version of Octyne fromGitHub Actions, or by compiling it yourself.
• Place octyne in a folder (on Linux/macOS/*nix, mark as executable withchmod +x <octyne file name>).
• Create aconfig.json next to Octyne (seehere for details).
• Run./<octyne file name> in a terminal in the folder to start Octyne. Anadmin user will be generated for you.
• You may want to getEcthelion to manage Octyne over the internet, andoctynectl as a CLI tool to manage Octyne locally on your machine.Additionally, make sure to follow the security practices here to prevent attacks against your setup!
• You might want to manage Octyne using systemd on Linux systems, which can start/stop Octyne, start it on boot, store its logs and restart it on crash.This article should help you out.

To get the current Octyne version, you can run./octyne --version or./octyne -v. This does not account for development builds.

Octyne depends on two files in the current working directory to get configuration from. Note that Octyne refers to apps as "servers" in the config and API for legacy reasons (due to originally being targeted towards web servers and Minecraft servers).

The path to these files can be customised using the--config=/path/to/config.json and--users=/path/to/users.json CLI flags (if relative, resolved relative to the working directory).

Used to configure the apps Octyne should start, Redis-based authentication for allowing more than a single node, Unix socket API, and HTTPS support. A reverse proxy can also be used for HTTPS if it supports WSS.

NOTE: Octyne supports comments and trailing commas in the config.json file, they don't need to be removed.

{"port":42069,// optional, default is 42069"unixSocket": {"enabled":true,// enables Unix socket API for auth-less actions by locally running apps e.g. octynectl"location":"",// optional, if absent, default is TMP/octyne.sock.PORT (see API.md for details)"group":""// optional, sets the socket's group owner, if absent, default is current user's primary group  },"redis": {"enabled":false,// whether the authentication tokens should sync to Redis for more than 1 node"url":"redis://localhost"// link to Redis server  },"https": {"enabled":false,// whether Octyne should listen using HTTP or HTTPS"cert":"/path/to/cert.pem",// path to HTTPS certificate"key":"/path/to/key.pem"// path to HTTPS private key  },"logging": {"enabled":true,// whether Octyne should log actions"path":"logs",// path to log files, can be relative or absolute"actions": {}// optional, disable logging for specific actions, more info below  },"servers": {"test1": {// each key has the name of the server"enabled":true,// optional, default true, Octyne won't auto-start when false"directory":"/home/test/server",// the directory in which the server is located"command":"java -jar spigot-1.12.2.jar"// the command to run to start the server    }  }}

Contains users who can log into Octyne. This file is automatically generated on first start with anadmin user and a generated secure password which is logged to terminal. You can perform account management via Ecthelion, octynectl or other such tools.

{"username":"password hashed with SHA-256 or Argon2id (recommended)"}

Note: actions performed locally using the Unix socket API by apps likeoctynectl are logged as being performed by the@local user, avoid using this username. Apps running on your PC under the same user as Octyne can use this API without a username or password.

Note: Fine-grained control over logging is currentlyexperimental. Therefore, action names may change in any version, not just major versions. However, we will generally try to avoid this in the interest of stability.

By default, Octyne will log all actions performed by users. You can enable/disable logging for specific actions by setting the action totrue orfalse in thelogging.actions object inconfig.json. For example, to disable logging forauth.login andauth.logout, youractions object would be:

"actions": {"auth.login":false,"auth.logout":false}

• Authentication (auth):login,logout
• Configuration (config):reload,view,edit
• Account management (accounts):create,update,delete
• Server management (server):
  • Top-level actions:start,stop,kill
  • Console (server.console):access,input
  • Files (server.files):upload,download,createFolder,delete,move,copy,bulk,compress,decompress

Use HTTPS to ensure end-to-end secure transmission. This is easy with Certbot and a reverse proxy like nginx or Apache (if you don't want to use Octyne's built-in HTTPS support). A reverse proxy can rate limit requests to Octyne as well, and put both Octyne and Ecthelion behind the same domain under different endpoints too! (⚠️ Or, under different subdomains, if you want, but this interferes with cookie authentication.)

location/console{# Remember to set the basePath in Ecthelion's config.json to /console (or whatever you pick)!proxy_pass http://127.0.0.1:3000;proxy_set_header X-Forwarded-For$proxy_add_x_forwarded_for;}location/octyne{rewrite/octyne/(.*)/$1 break;proxy_pass http://127.0.0.1:42069;proxy_set_header X-Forwarded-For$proxy_add_x_forwarded_for;# Adjust this as necessary for file uploads:client_max_body_size1024M;# Required for WebSocket functionality to work:proxy_http_version1.1;proxy_set_header Upgrade$http_upgrade;proxy_set_header Connection"Upgrade";}

Note: Ensuremod_proxy is loaded.

<VirtualHost*:443># Remember to set the basePath in Ecthelion's config.json to /console (or whatever you pick)!# EcthelionProxyPass /console http://127.0.0.1:4200/consoleProxyPassReverse /console http://127.0.0.1:4200/console# Octyne  Protocols h2 h2c http/1.1ProxyPassMatch ^/octyne/(server/.*/console)$  ws://127.0.0.1:42069/$1ProxyPass /octyne http://127.0.0.1:42069ProxyPassReverse /octyne http://127.0.0.1:42069</VirtualHost>