xray

Documentation

Overview

Package xray parses and renders xray-core configuration documents.

Index

• Variables
• func DefaultTemplate(opts TemplateOptions) (json.RawMessage, error)
• func GeneratePassword(bytes int) string
• func GenerateShortIDs(count int) ([]string, error)
• func NewWireGuardKey() (private, public string, err error)
• func ParseInbounds(raw json.RawMessage) ([]domain.ConfigProfileInbound, error)
• func Render(profile json.RawMessage, opts RenderOptions) ([]byte, string, error)
• func SortedTags(raw json.RawMessage) []string
• func Validate(raw json.RawMessage) error
• func WireGuardAddress(index int64) string
• func WireGuardPublicKey(privateKey string) (string, error)
• type Client
• type Document
• type RealityKeyPair
  • func GenerateRealityKeys() (*RealityKeyPair, error)
• type RenderOptions
• type Routing
• type TemplateOptions

Variables

var ErrNoInbounds = fmt.Errorf("configuration has no inbounds")

ErrNoInbounds signals a profile document that cannot serve any traffic.

Functions

func DefaultTemplate

func DefaultTemplate(opts TemplateOptions) (json.RawMessage, error)

DefaultTemplate builds a VLESS + REALITY profile that is ready to serve traffic as soon as a node picks it up, so a fresh install is never staring at an empty editor.

func GeneratePassword

func GeneratePassword(bytes int) string

GeneratePassword returns a base64 secret suitable for trojan or the 2022-blake3 shadowsocks ciphers, which require a 32-byte key.

func GenerateShortIDs

func GenerateShortIDs(count int) ([]string, error)

GenerateShortIDs returns REALITY shortIds: even-length hex strings of at most 16 characters.

func NewWireGuardKey

func NewWireGuardKey() (private, public string, err error)

NewWireGuardKey returns a private key and the public key derived from it.

func ParseInbounds

func ParseInbounds(raw json.RawMessage) ([]domain.ConfigProfileInbound, error)

ParseInbounds extracts the inbound summary rows persisted alongside a profile.

func Render

func Render(profile json.RawMessage, opts RenderOptions) ([]byte, string, error)

Render produces the exact configuration a node should run, together with a hash that lets the agent skip a restart when nothing changed.

func SortedTags

func SortedTags(raw json.RawMessage) []string

SortedTags returns the inbound tags of a document in a stable order.

func Validate

func Validate(raw json.RawMessage) error

Validate checks that a profile document is well formed and every inbound carries a unique, non-empty tag. Tags are the join key between profiles, nodes, squads and hosts, so a missing tag is a hard error rather than a warning.

func WireGuardAddress

func WireGuardAddress(index int64) string

WireGuardAddress maps a user's index onto an address inside the tunnel.

10.66.x.y gives roughly 65 000 subscribers per deployment. The first usable host is .2 because .0 and .1 are conventionally the network and the server, and handing a subscriber the address the server answers on is a fault that only shows up under load.

func WireGuardPublicKey

func WireGuardPublicKey(privateKey string) (string, error)

WireGuardPublicKey derives the public half of a stored private key. The server key lives in the operator's profile document, and a client config has to name the server's *public* key — so it is computed rather than asked for, which is one fewer field to get wrong.

Types

type Client

type Client struct {
	Email      string
	VlessUUID  string
	TrojanPass string
	SSPass     string
	Flow       string

	// WireGuard identifies a peer by its public key and the address it may use
	// inside the tunnel. The private half never leaves the panel — a node only
	// ever needs the public key.
	WGPublicKey string
	WGAddress   string
}

Client is a user entry injected into an inbound.

type Document

type Document struct {
	Log       json.RawMessage   `json:"log,omitempty"`
	DNS       json.RawMessage   `json:"dns,omitempty"`
	Inbounds  []json.RawMessage `json:"inbounds"`
	Outbounds []json.RawMessage `json:"outbounds,omitempty"`
	Routing   *Routing          `json:"routing,omitempty"`
	Policy    json.RawMessage   `json:"policy,omitempty"`
	API       json.RawMessage   `json:"api,omitempty"`
	Stats     json.RawMessage   `json:"stats,omitempty"`
	Transport json.RawMessage   `json:"transport,omitempty"`
	Reverse   json.RawMessage   `json:"reverse,omitempty"`
	FakeDNS   json.RawMessage   `json:"fakedns,omitempty"`
	Metrics   json.RawMessage   `json:"metrics,omitempty"`
	Observ    json.RawMessage   `json:"observatory,omitempty"`
	Burst     json.RawMessage   `json:"burstObservatory,omitempty"`
}

Document is the subset of an xray-core config the panel needs to reason about. Everything else is preserved verbatim through Extra.

type RealityKeyPair

type RealityKeyPair struct {
	PrivateKey string `json:"privateKey"`
	PublicKey  string `json:"publicKey"`
}

RealityKeyPair is an x25519 pair in the encoding xray-core expects.

func GenerateRealityKeys

func GenerateRealityKeys() (*RealityKeyPair, error)

GenerateRealityKeys mirrors `xray x25519`, so the panel can provision REALITY inbounds without shelling out to the binary.

type RenderOptions

type RenderOptions struct {
	// ActiveTags restricts the rendered document to these inbounds. Empty means
	// every inbound of the profile.
	ActiveTags []string
	// ClientsByTag maps an inbound tag to the users allowed to use it.
	ClientsByTag map[string][]Client
	// APIListen is the address the stats API listens on inside the node.
	APIListen string
	APIPort   int
}

RenderOptions controls how a node-specific config is produced from a profile.

type Routing

type Routing struct {
	DomainStrategy string            `json:"domainStrategy,omitempty"`
	DomainMatcher  string            `json:"domainMatcher,omitempty"`
	Rules          []json.RawMessage `json:"rules,omitempty"`
	Balancers      []json.RawMessage `json:"balancers,omitempty"`
}

type TemplateOptions

type TemplateOptions struct {
	InboundTag  string
	Port        int
	ServerNames []string
	PrivateKey  string
	ShortIDs    []string
	Dest        string
}

TemplateOptions parameterises the starter profile created on first boot.