fossil

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 19, 2020 License: MIT Imports: 7 Imported by: 0

README

Fossil

Go Report Card Build Status Coverage License GoDoc

Fossil is a pure Go wrapper library for the Pterodactyl API and it's descendants. It allows client-wise and administrator-wise operations for easy and automated server, user, node, egg and location management.

Contents:

Installation

Fossil can be installed using the integrated Go package manager:

go get github.com/camilohernandez/fossil

Examples

Client API

A Client gets access to all the functionalities a user might find on their server control panel. A Client Token is requiered for the Creation of a Client. To start a new Client use the NewClient() function:

import "github.com/camilohernandez/fossil"

client := fossil.NewClient("https://example.com","NRVW42TME45WW3B3E5VTWOZ3MFZWIYLTMRQXGZDBMFZWIYLT") // Panel URL and Client Token

Servers

Fetch all servers
servers, err := client.GetServers()
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

for _, s := range servers {
    fmt.Printf("ID: %s\n", s.ID)
    fmt.Printf("Name: %s\n", s.Name)
    fmt.Printf("Description: %s\n", s.Description)
}
Fetch a specific server
server, err := client.GetServer("6a185444")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

fmt.Printf("ID: %s\n", server.ID)
fmt.Printf("Name: %s\n", server.Name)
fmt.Printf("Description: %s\n", server.Description)

Get a server's status and usage
status, err := client.GetServerStatus("6a185444")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

fmt.Printf("State: %s\n", status.State)
fmt.Printf("CPU Current: %f\n", server.CPU.Current)
fmt.Printf("Memory used: %d\n", server.Memory.Used)
fmt.Printf("Disk used: %s\n", server.Disk.Used)

Server Actions

Turn server on
err := client.SetPowerState("6a185444", fossil.ON)
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Execute a command on a server
err := client.ExecuteCommand("6a185444", "say Hello!")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Application API

An Application connection allows full access to server, user, location, nest and egg management. With Application calls you have full administrator-level access to the creation of users and servers. An Application Token (also called "API Token") is required to create an Application object. To start a new Application use the NewApplication() function:

import "github.com/camilohernandez/fossil"

app := fossil.NewApplication("https://example.com","OF3WK4LXMVYXOZLYMRQXQWTYMFZWIYLTMRQXGZDBOM") // Panel URl and Application Token

Servers

When interacting servers with an Application Token you get extra information, and more functions.

Fetch all servers
servers, err := app.GetServers()
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

for _, s := range servers {
    fmt.Printf("ID: %d\n", s.ID)
    fmt.Printf("Name: %s\n", s.Name)
    fmt.Printf("Description: %s\n", s.Description)
    fmt.Printf("Node: %d\n", s.Node)
    fmt.Printf("Nest: %d\n\n", s.Nest)
}
Get a server with its Internal ID
server, err := app.GetServer(17)
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}
Get a server with its External ID
server, err := app.GetServerExternal("test_server1")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Create a new server
server := &fossil.ApplicationServer{
    Name:        "Test Server",
    Description: "A server to test the Fossil library",
    ExternalID:  "test_server1",
    User:        12,
    Node:        2,
    Nest:        5,
    Egg:         20,
    Container: fossil.Container{
        StartupCommand: "java -Xms128M -Xmx 1024M -jar server.jar",
        Image:          "quay.io/pterodactyl/core:java-glibc", // Minecraft
        Environment: map[string]string{ // WISP Requieres some aditional enviroment variables for SRCDS images:
            "DL_VERSION": "1.12.2",     // SRCDS_APPID, STEAM_ACC, SRCDS_MAP
        },
    },
    Limits: fossil.Limits{
        Memory:    512,
        Swap:      512,
        Disk:      1024,
        IO:        500,
        CPU:       100,
        Databases: 1,
    },
    Allocation: 9000,
}

err := app.CreateServer(server)
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Change a server's name, user, external ID or description
sv, err := app.GetServer(17)
if err != nil {
    fmt.Println(err.Error())
    return
}

sv.Name = "Fossil Test"

err = app.UpdateDetails(sv)
if err != nil {
    fmt.Println(err.Error())
}
Change a server's limits or allocations
sv, err := app.GetServer(17)
if err != nil {
    fmt.Println(err.Error())
    return
}

sv.Limits = fossil.Limits{
    Memory:      1024,
    Databases:   2,
    Allocations: 2,
}

err = app.UpdateBuild(sv, []int{9001, 9002},[]int{9000}) // Add allocations 9001 and 9002, delete 9000
if err != nil {
    fmt.Println(err.Error())
    return
}
Change a server's image settings
sv, err := app.GetServer(17)
if err != nil {
    fmt.Println(err.Error())
    return
}

sv.Container = fossil.Container{
    StartupCommand: "java -Xms128M -Xmx 1024M -jar server.jar",
    Image:          "quay.io/pterodactyl/core:java-glibc", // Minecraft
    Environment: map[string]string{
        "DL_VERSION": "1.12.2",
    },
}

err = app.UpdateStartup(sv)
if err != nil {
    fmt.Println(err.Error())
    return
}

Suspend or unsuspend a server
err := app.SuspendServer(17) // Suspending server with Internal ID 17 
if err != nil {
    fmt.Println(err.Error())
    return
}

err = app.UnsuspendServer(17) // Unsuspending server with Internal ID 17 
if err != nil {
    fmt.Println(err.Error())
    return
}

Rebuild or reinstall a server
err := app.RebuildServer(17) // Rebuilding server with Internal ID 17
if err != nil {
    fmt.Println(err.Error())
    return
}

err = app.ReinstallServer(17) // Reinstalling server with Internal ID 17
if err != nil {
    fmt.Println(err.Error())
    return
}

Delete a server
err := app.DeleteServer(17) // Deleting server with Internal ID 17
if err != nil {
    fmt.Println(err.Error())
    return
}

err = app.ForceDeleteServer(17) // DeleteServer should allays be preferred, as ForceDeleteServer
if err != nil {                 // is an unsafe operation.
    fmt.Println(err.Error())
    return
}

Databases

Fetch all databases
dbs, err := app.GetDatabases()
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, db := range dbs{
    fmt.Println(db.Database)
}
Fetch a specific database
db, err := app.GetDatabase(17, 1) // Get database 1 in server 17
if err != nil {
    fmt.Println(err.Error())
    return
}

Create a database
db := &fossil.Database{
    Database: "fossil_test",
    Host:      15, // The server 15 will be the host server
    Remote:    "%", // IPs and wildcards work
}

err := app.CreateDatabase(17, db)
if err != nil {
    fmt.Println(err.Error())
    return
}

Delete a database
err := app.DeleteDatabase(17, 1) // Delete database 1 in server 17
if err != nil {
    fmt.Println(err.Error())
    return
}

Users

Fetch all users
users, err := app.GetUsers()
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

for _, u := range users {
    fmt.Printf("ID: %d\n", u.ID)
    fmt.Printf("First Name: %s\n", u.FirstName)
    fmt.Printf("Last Name: %s\n\n", u.LastName)
}
Fetch a specific user
user, err := app.GetUser(4) // Get user of Internal ID 4
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Create a user
user := &fossil.User{
    ExternalID:              "test_user1",
    Username:                "TestUser",
    Email:                   "example@example.com",
    FirstName:               "John",
    LastName:                "Doe",
}

err := app.CreateUser(user, "password123")
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Update a user
user, err := app.GetUser(17)
if err != nil {
    return
}

user.FirstName = "John"

err = app.UpdateUser(user, "password123") // Password is optional
if err != nil {
    fmt.Println("ERROR: " + err.Error())
    return
}

Delete a user
err := app.DeleteUser(17)
if err != nil {
    return
}

Nests and eggs

Fetch nests
nests, err := app.GetNests()
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, n := range nests{
    fmt.Println(n.Name)
    fmt.Println(n.Description)
}
Fetch specific nest
nest, err := app.GetNest(2) // Get nest with ID 2 (Minecraft)
if err != nil {
    fmt.Println(err.Error())
    return
}

Fetch eggs inside a nest
eggs, err := app.GetEggs(2) // Get all the eggs for nest 2 (Minecraft)
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, e := range eggs{
    fmt.Println(e.ID)
    fmt.Println(e.Description)
}
Fetch specific egg inside a nest
egg, err := app.GetEgg(2, 2)
if err != nil {
    fmt.Println(err.Error())
    return
}

Locations

Fetch locations
locs, err := app.GetLocations()
if err != nil {
    fmt.Println(err.Error())
    return
}

for _, l := range locs{
    fmt.Println(l.ID)
    fmt.Println(l.Long)
}

Fetch location
loc, err := app.GetLocation(2) // Get location with ID 2
if err != nil {
    fmt.Println(err.Error())
    return
}
Fetch location
loc, err := app.GetLocation(2) // Get location with ID 2
if err != nil {
    fmt.Println(err.Error())
    return
}

Create a location
loc, err := app.CreatLocation("us.gameserver1", "USA Gameserver #1") // Short and long name
if err != nil {
    fmt.Println(err.Error())
    return
}

Modify a location's names
loc := GetLocation(2)

loc.ShortName = "us.datacenter"
loc.LongName = "US Datacenter"

err := app.UpdateLocationName(loc)
if err != nil {
    fmt.Println(err.Error())
    return
}

Delete a location
err := app.DeleteLocation(2) // Delete location with ID 2
if err != nil {
    fmt.Println(err.Error())
    return
}

Disclaimer

Fossil is partially based on the Crocgodyl library. All the respective kudos to the author.

Licence

This library is licensed under the MIT Licence, please refer to the LICENCE file for more information. The logo used in this project is provided by OpenClipart-Vectors, and is licenced under the Pixbay Licence.

Documentation

Overview

Package fossil provides a wrapper for the Pterodactyl and WISP APIs.

Index

Constants

View Source
const (
	ON      = "start"
	OFF     = "stop"
	RESTART = "restart"
	KILL    = "kill"
)

Power States

Variables

This section is empty.

Functions

This section is empty.

Types

type Allocation

type Allocation struct {
	Primary bool   `json:"primary"`
	IP      string `json:"ip"`
	Alias   string `json:"alias"`
	Port    int    `json:"port"`
}

Allocation holds all the information relating to the allocation data of a server

type ApplicationCredentials

type ApplicationCredentials Credentials

ApplicationCredentials allow you to authenticate as a administrator, and access nodes, servers users with creation and destruction privileges.

func NewApplication

func NewApplication(url, apiToken string) *ApplicationCredentials

NewApplication Creates a new ApplicationCredentials object used to interact with Pterodactyl as administrator.

func (*ApplicationCredentials) CreateDatabase

func (c *ApplicationCredentials) CreateDatabase(sid int, db *Database) (err error)

CreateDatabase creates a new database based on the provided information

func (*ApplicationCredentials) CreateLocation

func (c *ApplicationCredentials) CreateLocation(shortName, longName string) (loc *Location, err error)

CreateLocation makes a new location with the provided names

func (*ApplicationCredentials) CreateServer

func (c *ApplicationCredentials) CreateServer(sv *ApplicationServer) (err error)

CreateServer creates a new server

func (*ApplicationCredentials) CreateUser

func (c *ApplicationCredentials) CreateUser(u *User, password ...string) (err error)

CreateUser makes a new account with the provided data. The password argument can be optionally set.

func (*ApplicationCredentials) DeleteDatabase

func (c *ApplicationCredentials) DeleteDatabase(sid int, dbid int) (err error)

DeleteDatabase marks the specified database in the specified server for deletion

func (*ApplicationCredentials) DeleteLocation

func (c *ApplicationCredentials) DeleteLocation(lid int) (err error)

DeleteLocation marks a server as suspended

func (*ApplicationCredentials) DeleteServer

func (c *ApplicationCredentials) DeleteServer(sid int) (err error)

DeleteServer marks a server for deletion

func (*ApplicationCredentials) DeleteUser

func (c *ApplicationCredentials) DeleteUser(id int) (err error)

DeleteUser marks a user for deletion.

func (*ApplicationCredentials) ForceDeleteServer

func (c *ApplicationCredentials) ForceDeleteServer(sid int) (err error)

ForceDeleteServer forcefully deletes a server. This is an ungraceful way to delete the server, and when possible DeleteServer should be preferred.

func (*ApplicationCredentials) GetDatabase

func (c *ApplicationCredentials) GetDatabase(sid int, dbid int) (db *Database, err error)

GetDatabase fetches, if present, the database matching the id in the server's databases

func (*ApplicationCredentials) GetDatabases

func (c *ApplicationCredentials) GetDatabases(sid int) (dbs []*Database, err error)

GetDatabases fetches all the associated databases for a server

func (*ApplicationCredentials) GetEgg

func (c *ApplicationCredentials) GetEgg(nestID int, eggID int) (egg *Egg, err error)

GetEgg searches for a specific eggs inside a nest

func (*ApplicationCredentials) GetEggs

func (c *ApplicationCredentials) GetEggs(nestID int) (eggs []*Egg, err error)

GetEggs fetches all eggs inside a nest

func (*ApplicationCredentials) GetLocation

func (c *ApplicationCredentials) GetLocation(id int) (loc *Location, err error)

GetLocation fetches the location with the given ID

func (*ApplicationCredentials) GetLocations

func (c *ApplicationCredentials) GetLocations() (locations []*Location, err error)

GetLocations fetches all available locations

func (*ApplicationCredentials) GetNest

func (c *ApplicationCredentials) GetNest(id int) (nest *Nest, err error)

GetNest fetches, if present, a specific nest.

func (*ApplicationCredentials) GetNests

func (c *ApplicationCredentials) GetNests() (nests []*Nest, err error)

GetNests fetches all available nests

func (*ApplicationCredentials) GetServer

func (c *ApplicationCredentials) GetServer(internalID int) (sv *ApplicationServer, err error)

GetServer fetches the server with the given Internal ID if it exists

func (*ApplicationCredentials) GetServerExternal

func (c *ApplicationCredentials) GetServerExternal(externalID string) (sv *ApplicationServer, err error)

GetServerExternal fetches the server with the given External ID if it exists

func (*ApplicationCredentials) GetServers

func (c *ApplicationCredentials) GetServers() (svs []*ApplicationServer, err error)

GetServers fetches the servers of all the users

func (*ApplicationCredentials) GetUser

func (c *ApplicationCredentials) GetUser(id int) (user *User, err error)

GetUser fetches, if present, the user with the matching Internal ID

func (*ApplicationCredentials) GetUserExternal

func (c *ApplicationCredentials) GetUserExternal(eid string) (user *User, err error)

GetUserExternal fetches, if present, the user with the matching External ID

func (*ApplicationCredentials) GetUsers

func (c *ApplicationCredentials) GetUsers() (users []*User, err error)

GetUsers fetches all the registered users from the API

func (*ApplicationCredentials) RebuildServer

func (c *ApplicationCredentials) RebuildServer(sid int) (err error)

RebuildServer starts a server rebuild

func (*ApplicationCredentials) ReinstallServer

func (c *ApplicationCredentials) ReinstallServer(sid int) (err error)

ReinstallServer marks a server for reinstallation

func (*ApplicationCredentials) ResetDatabasePassword

func (c *ApplicationCredentials) ResetDatabasePassword(sid int, dbid int) (err error)

ResetDatabasePassword resets the password for the specified database of the specified server

func (*ApplicationCredentials) SuspendServer

func (c *ApplicationCredentials) SuspendServer(sid int) (err error)

SuspendServer marks a server as suspended

func (*ApplicationCredentials) UnsuspendServer

func (c *ApplicationCredentials) UnsuspendServer(sid int) (err error)

UnsuspendServer marks a server as active

func (*ApplicationCredentials) UpdateBuild

func (c *ApplicationCredentials) UpdateBuild(sv *ApplicationServer, addAlloc []int, removeAlloc []int) (err error)

UpdateBuild modifies the server's limit and allocation configuration

func (*ApplicationCredentials) UpdateDetails

func (c *ApplicationCredentials) UpdateDetails(sv *ApplicationServer) (err error)

UpdateDetails modifies the server name, user, external id and description

func (*ApplicationCredentials) UpdateLocationName

func (c *ApplicationCredentials) UpdateLocationName(loc *Location) (err error)

UpdateLocationName modifies the short and long names of a location

func (*ApplicationCredentials) UpdateStartup

func (c *ApplicationCredentials) UpdateStartup(sv *ApplicationServer) (err error)

UpdateStartup modifies the server's startup parameters, egg and image configuration

func (*ApplicationCredentials) UpdateUser

func (c *ApplicationCredentials) UpdateUser(u *User, password ...string) (err error)

UpdateUser modifies the user as per the passed object. Be aware that not all parameters can be modified. Modifiable parameters include: External ID, Username, First name, Last name, Password, Root admin and Language. The password parameter can be optionally set.

type ApplicationServer

type ApplicationServer struct {
	ID                 int
	Name               string
	Description        string
	Limits             Limits
	ExternalID         string
	UUID               string
	Suspended          bool
	User               int
	Node               int
	Nest               int
	Egg                int
	Pack               int
	Allocation         int
	AllocationsDetails []Allocation
	Container          Container
	Updated            time.Time
	Created            time.Time
}

ApplicationServer defines Pterodactyl server as an administrator would see it. It is fetched and interacted with the api token.

func (*ApplicationServer) String

func (s *ApplicationServer) String() string

type CPU

type CPU struct {
	Current float32
	Cores   []float32
	Limit   uint64
}

CPU holds the usage, core status and limits of the server CPU

type ClientCredentials

type ClientCredentials Credentials

ClientCredentials are user-specific, and can only be used to access and modify servers associated with that user. They do not allow administrator-level control of the servers.

func NewClient

func NewClient(url, clientToken string) *ClientCredentials

NewClient creates a new ClientCredentials object used to interact with Pterodactyl as a user.

func (*ClientCredentials) ExecuteCommand

func (c *ClientCredentials) ExecuteCommand(id string, cmd string) (err error)

ExecuteCommand allows the execution of a console command on the specified server

func (*ClientCredentials) GetServer

func (c *ClientCredentials) GetServer(id string) (sv *ClientServer, err error)

GetServer fetches the server with the given ID if it exists

func (*ClientCredentials) GetServerStatus

func (c *ClientCredentials) GetServerStatus(id string) (ss *ServerStatus, err error)

GetServerStatus fetches the server's status and usage

func (*ClientCredentials) GetServers

func (c *ClientCredentials) GetServers() (svs []*ClientServer, err error)

GetServers fetches all the servers of the client

func (*ClientCredentials) SetPowerState

func (c *ClientCredentials) SetPowerState(id string, state string) (err error)

SetPowerState changes the power state of a server. Will result in error if the server is already in that state or is unable to change state.

type ClientServer

type ClientServer struct {
	ID                string
	Name              string
	Description       string
	Limits            Limits
	AllocationDetails []Allocation
	IsOwner           bool
}

ClientServer defines Pterodactyl server as a user would see it. It is fetched and interacted with the client token.

func (*ClientServer) String

func (s *ClientServer) String() string

type Container

type Container struct {
	StartupCommand string            `json:"startup_command"`
	Image          string            `json:"image"`
	Installed      bool              `json:"installed"`
	Environment    map[string]string `json:"environment"`
}

Container holds all the Docker Image settings

type Credentials

type Credentials struct {
	URL   string
	Token string
}

Credentials is the base object for ClientCredentials and ApplicationCredentials, and should not be used independently.

type Database

type Database struct {
	ID        int       `json:"id"`
	Server    int       `json:"server"`
	Host      int       `json:"host"`
	Database  string    `json:"database"`
	Username  string    `json:"username"`
	Remote    string    `json:"remote"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Database contains all the information of a specific Pterodactyl database

type Disk

type Disk struct {
	Used  uint64
	Limit uint64
}

Disk holds the usage and limits of the server disk

type Egg

type Egg struct {
	ID          int       `json:"id"`
	UUID        string    `json:"uuid"`
	Nest        int       `json:"nest"`
	Author      string    `json:"author"`
	Description string    `json:"description"`
	DockerImage string    `json:"docker_image"`
	Config      EggConfig `json:"config"`
	Startup     string    `json:"startup"`
	Script      EggScript `json:"script"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Egg represents the information regarding an egg

type EggConfig

type EggConfig struct {
	Startup      EggStartup `json:"startup"`
	Stop         string     `json:"stop"`
	CustomConfig []string   `json:"custom_config"`
	Extends      string     `json:"extends"`
}

EggConfig represents the configurations of an egg

type EggScript

type EggScript struct {
	Privileged bool   `json:"privileged"`
	Install    string `json:"install"`
	Entry      string `json:"entry"`
	Container  string `json:"container"`
	Extends    string `json:"extends"`
}

EggScript represents the script configuration of an egg

type EggStartup

type EggStartup struct {
	Done            string   `json:"done"`
	UserInteraction []string `json:"userInteraction"`
}

EggStartup represents the startup settings of an egg

type Limits

type Limits struct {
	Memory      int `json:"memory"`
	Swap        int `json:"swap"`
	Disk        int `json:"disk"`
	IO          int `json:"io"`
	CPU         int `json:"cpu"`
	Databases   int `json:"-"`
	Allocations int `json:"-"`
}

Limits contains all the allocated usage limits set for a server

type Location

type Location struct {
	ID        int       `json:"id"`
	ShortName string    `json:"short"`
	LongName  string    `json:"long"`
	UpdatedAt time.Time `json:"updated_at"`
	CreatedAt time.Time `json:"created_at"`
}

Location represents a server location

type Memory

type Memory struct {
	Used  uint64
	Limit uint64
}

Memory holds the usage and limits of the server memory

type Meta

type Meta struct {
	Pagination struct {
		Total       int `json:"total"`
		Count       int `json:"count"`
		PerPage     int `json:"per_page"`
		CurrentPage int `json:"current_page"`
		TotalPages  int `json:"total_pages"`
		Links       struct {
			Previous string `json:"previous,omitempty"`
			Next     string `json:"next,omitempty"`
		} `json:"links"`
	} `json:"pagination"`
}

Meta contains the metadata of an API response

type Nest

type Nest struct {
	ID          int       `json:"id"`
	UUID        string    `json:"uuid"`
	Author      string    `json:"author"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Nest represents the information regarding a nest

type Players

type Players struct {
	Current uint64
	Limit   uint64
}

Players holds the number of users in a server and the max amount permitted. Some Pterodactyl API-based software DO NOT provide this information.

type ServerStatus

type ServerStatus struct {
	State   string
	Memory  Memory
	CPU     CPU
	Disk    Disk
	Players Players
}

ServerStatus contains the client-visible server usage information

type User

type User struct {
	ID                      int       `json:"id"`
	ExternalID              string    `json:"external_id"`
	UUID                    string    `json:"uuid"`
	Username                string    `json:"username"`
	Email                   string    `json:"email"`
	FirstName               string    `json:"first_name"`
	LastName                string    `json:"last_name"`
	Language                string    `json:"language"`
	RootAdmin               bool      `json:"root_admin"`
	TwoFactorAuthentication bool      `json:"2fa"`
	CreatedAt               time.Time `json:"created_at"`
	UpdatedAt               time.Time `json:"updated_at"`
}

User holds user information

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL