Documentation
¶
Index ¶
Constants ¶
const ( ConsoleOutputEvent = "console output" StateChangeEvent = "state change" ResourceEvent = "resources" DockerImagePullStarted = "docker image pull started" DockerImagePullStatus = "docker image pull status" DockerImagePullCompleted = "docker image pull completed" )
const ( ProcessOfflineState = "offline" ProcessStartingState = "starting" ProcessRunningState = "running" ProcessStoppingState = "stopping" )
Variables ¶
This section is empty.
Functions ¶
func ConfigureDocker ¶
func ConfigureDocker(c *config.DockerConfiguration) error
Configures the required network for the docker environment.
func DockerClient ¶
Return a Docker client to be used throughout the codebase. Once a client has been created it will be returned for all subsequent calls to this function.
Types ¶
type Allocations ¶
type Allocations struct {
// Defines the default allocation that should be used for this server. This is
// what will be used for {SERVER_IP} and {SERVER_PORT} when modifying configuration
// files or the startup arguments for a server.
DefaultMapping struct {
Ip string `json:"ip"`
Port int `json:"port"`
} `json:"default"`
// Mappings contains all of the ports that should be assigned to a given server
// attached to the IP they correspond to.
Mappings map[string][]int `json:"mappings"`
}
Defines the allocations available for a given server. When using the Docker environment driver these correspond to mappings for the container that allow external connections.
func (*Allocations) Bindings ¶
func (a *Allocations) Bindings() nat.PortMap
Converts the server allocation mappings into a format that can be understood by Docker. While we do strive to support multiple environments, using Docker's standardized format for the bindings certainly makes life a little easier for managing things.
You'll want to use DockerBindings() if you need to re-map 127.0.0.1 to the Docker interface.
func (*Allocations) DockerBindings ¶
func (a *Allocations) DockerBindings() nat.PortMap
Returns the bindings for the server in a way that is supported correctly by Docker. This replaces any reference to 127.0.0.1 with the IP of the pterodactyl0 network interface which will allow the server to operate on a local address while still being accessible by other containers.
func (*Allocations) Exposed ¶
func (a *Allocations) Exposed() nat.PortSet
Converts the server allocation mappings into a PortSet that can be understood by Docker. This formatting is slightly different than "Bindings" as it should return an empty struct rather than a binding.
To accomplish this, we'll just get the values from "DockerBindings" and then set them to empty structs. Because why not.
type Configuration ¶
type Configuration struct {
// contains filtered or unexported fields
}
Defines the actual configuration struct for the environment with all of the settings defined within it.
func NewConfiguration ¶
func NewConfiguration(s Settings, envVars []string) *Configuration
Returns a new environment configuration with the given settings and environment variables defined within it.
func (*Configuration) Allocations ¶
func (c *Configuration) Allocations() Allocations
Returns the allocations associated with this environment.
func (*Configuration) EnvironmentVariables ¶
func (c *Configuration) EnvironmentVariables() []string
Returns the environment variables associated with this instance.
func (*Configuration) Limits ¶
func (c *Configuration) Limits() Limits
Returns the limits assigned to this environment.
func (*Configuration) Mounts ¶
func (c *Configuration) Mounts() []Mount
Returns all of the mounts associated with this environment.
func (*Configuration) SetEnvironmentVariables ¶
func (c *Configuration) SetEnvironmentVariables(ev []string)
Updates the environment variables associated with this environment by replacing the entire array of them with a new one.
func (*Configuration) SetSettings ¶
func (c *Configuration) SetSettings(s Settings)
Updates the settings struct for this environment on the fly. This allows modified servers to automatically push those changes to the environment.
type Limits ¶
type Limits struct {
// The total amount of memory in megabytes that this server is allowed to
// use on the host system.
MemoryLimit int64 `json:"memory_limit"`
// The amount of additional swap space to be provided to a container instance.
Swap int64 `json:"swap"`
// The relative weight for IO operations in a container. This is relative to other
// containers on the system and should be a value between 10 and 1000.
IoWeight uint16 `json:"io_weight"`
// The percentage of CPU that this instance is allowed to consume relative to
// the host. A value of 200% represents complete utilization of two cores. This
// should be a value between 1 and THREAD_COUNT * 100.
CpuLimit int64 `json:"cpu_limit"`
// The amount of disk space in megabytes that a server is allowed to use.
DiskSpace int64 `json:"disk_space"`
// Sets which CPU threads can be used by the docker instance.
Threads string `json:"threads"`
OOMDisabled bool `json:"oom_disabled"`
}
The build settings for a given server that impact docker container creation and resource limits for a server instance.
func (*Limits) BoundedMemoryLimit ¶
func (*Limits) ConvertedCpuLimit ¶
Converts the CPU limit for a server build into a number that can be better understood by the Docker environment. If there is no limit set, return -1 which will indicate to Docker that it has unlimited CPU quota.
func (*Limits) ConvertedSwap ¶
Returns the amount of swap available as a total in bytes. This is returned as the amount of memory available to the server initially, PLUS the amount of additional swap to include which is the format used by Docker.
func (*Limits) MemoryOverheadMultiplier ¶
Set the hard limit for memory usage to be 5% more than the amount of memory assigned to the server. If the memory limit for the server is < 4G, use 10%, if less than 2G use 15%. This avoids unexpected crashes from processes like Java which run over the limit.
type Mount ¶
type Mount struct {
// In Docker environments this makes no difference, however in a non-Docker environment you
// should treat the "Default" mount as the root directory for the server. All other mounts
// are just in addition to that one, and generally things like shared maps or timezone data.
Default bool `json:"-"`
// The target path on the system. This is "/home/container" for all server's Default mount
// but in non-container environments you can likely ignore the target and just work with the
// source.
Target string `json:"target"`
// The directory from which the files will be read. In Docker environments this is the directory
// that we're mounting into the container at the Target location.
Source string `json:"source"`
// Whether or not the directory is being mounted as read-only. It is up to the environment to
// handle this value correctly and ensure security expectations are met with its usage.
ReadOnly bool `json:"read_only"`
}
type ProcessEnvironment ¶
type ProcessEnvironment interface {
// Returns the name of the environment.
Type() string
// Returns the environment configuration to the caller.
Config() *Configuration
// Returns an event emitter instance that can be hooked into to listen for different
// events that are fired by the environment. This should not allow someone to publish
// events, only subscribe to them.
Events() *events.EventBus
// Determines if the server instance exists. For example, in a docker environment
// this should confirm that the container is created and in a bootable state. In
// a basic CLI environment this can probably just return true right away.
Exists() (bool, error)
// Determines if the environment is currently active and running a server process
// for this specific server instance.
IsRunning() (bool, error)
// Performs an update of server resource limits without actually stopping the server
// process. This only executes if the environment supports it, otherwise it is
// a no-op.
InSituUpdate() error
// Runs before the environment is started. If an error is returned starting will
// not occur, otherwise proceeds as normal.
OnBeforeStart() error
// Starts a server instance. If the server instance is not in a state where it
// can be started an error should be returned.
Start() error
// Stops a server instance. If the server is already stopped an error should
// not be returned.
Stop() error
// Waits for a server instance to stop gracefully. If the server is still detected
// as running after seconds, an error will be returned, or the server will be terminated
// depending on the value of the second argument.
WaitForStop(seconds uint, terminate bool) error
// Terminates a running server instance using the provided signal. If the server
// is not running no error should be returned.
Terminate(signal os.Signal) error
// Destroys the environment removing any containers that were created (in Docker
// environments at least).
Destroy() error
// Returns the exit state of the process. The first result is the exit code, the second
// determines if the process was killed by the system OOM killer.
ExitState() (uint32, bool, error)
// Creates the necessary environment for running the server process. For example,
// in the Docker environment create will create a new container instance for the
// server.
Create() error
// Attaches to the server console environment and allows piping the output to a
// websocket or other internal tool to monitor output. Also allows you to later
// send data into the environment's stdin.
Attach() error
// Sends the provided command to the running server instance.
SendCommand(string) error
// Reads the log file for the process from the end backwards until the provided
// number of lines is met.
Readlog(int) ([]string, error)
}
Defines the basic interface that all environments need to implement so that a server can be properly controlled.
type Settings ¶
type Settings struct {
Mounts []Mount
Allocations Allocations
Limits Limits
}
type Stats ¶
type Stats struct {
// The total amount of memory, in bytes, that this server instance is consuming. This is
// calculated slightly differently than just using the raw Memory field that the stats
// return from the container, so please check the code setting this value for how that
// is calculated.
Memory uint64 `json:"memory_bytes"`
// The total amount of memory this container or resource can use. Inside Docker this is
// going to be higher than you'd expect because we're automatically allocating overhead
// abilities for the container, so its not going to be a perfect match.
MemoryLimit uint64 `json:"memory_limit_bytes"`
// The absolute CPU usage is the amount of CPU used in relation to the entire system and
// does not take into account any limits on the server process itself.
CpuAbsolute float64 `json:"cpu_absolute"`
// Current network transmit in & out for a container.
Network struct {
RxBytes uint64 `json:"rx_bytes"`
TxBytes uint64 `json:"tx_bytes"`
} `json:"network"`
// contains filtered or unexported fields
}
Defines the current resource usage for a given server instance. If a server is offline you should obviously expect memory and CPU usage to be 0. However, disk will always be returned since that is not dependent on the server being running to collect that data.
type Variables ¶
type Variables map[string]interface{}
func (Variables) Get ¶
Ugly hacky function to handle environment variables that get passed through as not-a-string from the Panel. Ideally we'd just say only pass strings, but that is a fragile idea and if a string wasn't passed through you'd cause a crash or the server to become unavailable. For now try to handle the most likely values from the JSON and hope for the best.
Source Files
Directories