base

README

Configuration Parameters for replicatr

This document provides detailed explanations of the configurable parameters and subcommands for replicatr. These parameters can be set when running the relay, allowing for customization according to the operational needs.

General Usage

go run . <flags> <args> <subcommand> <subcommand flags> <subcommand args>

Note: all subcommands will execute the command and exit. The relay will not continue to run after the subcommand as in the general case. Only one subcommand should be given per call

Stored Settings

By default, replicatr creates a profile folder in $HOME/replicatr. use the -p or --profile folder to change the name; the location is not configurable, however. Add a dot prefix to have it hidden from regular directory listings eg -p .localcache

Inside this folder will be stored two configuration files, config.json and info.json. The first contains persistent settings based on the CLI arguments shown above, and the second contains a NIP-11 Relay Information Document. Any relevant parameters set on the command line will override those found in these two files (such as --auth) for the duration of the run. See below for all configurable parameters and subcommands.

Options

Network and Identity

• --listen, -l
  Sets the network address that the relay listens on.

  • Example: -l 0.0.0.0:8080

• --canisteraddr, -C
  Specifies the IC canister address to use.

  • Local: -C http://127.0.0.1:<Port Number>
  • Main Net: -C https://icp0.io/

• --canisterid, -I
  The IC canister ID to be used.

  • Example: -I abcde-fghij-klmno-pqrst-uvw

• --seckey, -s
  Identity key of the relay, used for various security functions.

  • Example: -s mySecretKey

Configuration and Metadata

• --profile, -p
  Defines the profile name to use for storage, defaults to replicatr.

  • Example: -p myProfile

• --name, -n
  Sets the name of the relay for NIP-11.

  • Example: -n MyRelay

• --description, -d
  Provides a description of the relay for NIP-11.

  • Example: -d "My custom relay"

• --pubkey
  Public key of the relay operator.

  • Example: --pubkey 123abc

• --contact, -c
  Contact details of the relay operator.

  • Example: -c email@example.com

• --icon, -i
  Icon to show on relay information pages.

  • Example: -i http://example.com/icon.png

Access Control

• --auth, -a
  Requires NIP-42 authentication for all access.

  • Example: -a

• --public
  Allows public read access to users not on the access control list.

  • Example: --public

• --owner, -o
  Specifies public keys of users with owner-level permissions on the relay.

  • Example: -o pubkey1,pubkey2

• --whitelist, -w
  IP addresses that are only allowed to access.

  • Example: -w 192.168.1.1

• --allow, -A
  IP addresses that are always allowed to access.

  • Example: -A 192.168.1.1

• --auth,a Enable mandating NIP-42 authentication for all access

  • Example: -a,--auth

• --owners,-o specify public keys of users with owner level permissions on relay

  • Example: -o a432trafdfafd,dafrt4atgargfdfe

Performance and Resource Management

• --eventstore,-e Select event store backend

  • Options: ic, badger, iconly
  • Example: -e ic

• --sizelimit, -S
  Sets the maximum size of the event store in bytes.

  • Example: -S 1000000

• --lowwater, -L
  Target percentage for database size during garbage collection.

  • Example: -L 20

• --highwater, -H
  Trigger percentage for database size during garbage collection.

  • Example: -H 80

• --gcfreq, -G
  Frequency in seconds to check if database needs garbage collection.

  • Example: -G 3600

• --maxprocs
  Maximum number of goroutines to use.

  • Example: --maxprocs 8

• --loglevel
  Sets the log level.

  • Options: off, fatal, error, warn, info, debug, trace
  • Example: --loglevel debug

• --pprof
  Enables CPU and memory profiling.

  • Example: --pprof

• --gcratio
  GC percentage for triggering GC sweeps.

  • Example: --gcratio 50

• --memlimit
  Sets a memory limit on the process to constrain memory usage.

  • Example: --memlimit 500MB

• --pollfrequency
  Frequency of polling if a level 2 event store is enabled.

  • Example: --pollfrequency 5

• --polloverlap
  Overlap multiple of poll frequency to account for latency.

  • Example: --polloverlap 2

Commands

Note: all subcommands will execute the command and exit. The relay will not continue to run as in the general case. Only one subcommand should be given per call.

• initcfg
  Initialize relay configuration files.

• export
  Export database as line-structured JSON.

• import
  Import data from line-structured JSON.

• pubkey
  Print relay's canister public key.

• addrelay
  Add a relay to the cluster - only an Owner relay is authorized to do this

  • --addpubkey
    Public key of the client to add.
    • Example: addrelay --addpubkey 987xyz
  • --admin
    Set client as an admin.
    • Example: add relay --addpubkey 987xyz --admin

• removerelay
  Remove a relay from the cluster - only an Owner relay is authorized to do this

  • --removepubkey
    Public key of the client to remove.
    • Example: removerelay --removepubkey 987xyz

• getpermission
  Obtain the access-level of a relay.

  • Options: Owner, User, Unauthorized

• wipebdb
  Empties local badger database (bdb).

Documentation

Index

• type AddRelay
• type Config
  • func GetDefaultConfig() *Config
  • func (c *Config) Load(filename string) (err error)
  • func (c *Config) Save(filename string) (err error)
• type ExportCmd
• type GetPermission
• type ImportCmd
• type InitCfg
• type PubKey
• type RemoveRelay
• type RescanAC
• type WipeBDB

Types

type AddRelay

type AddRelay struct {
	PubKey string `arg:"--addpubkey" help:"public key of client to add"`
	Admin  bool   `arg:"--admin"  help:"set client as admin"`
}

type Config

type Config struct {
	InitCfgCmd       *InitCfg       `arg:"subcommand:initcfg" json:"-" help:"initialize relay configuration files"`
	ExportCmd        *ExportCmd     `arg:"subcommand:export" json:"-" help:"export database as line structured JSON"`
	ImportCmd        *ImportCmd     `arg:"subcommand:import" json:"-" help:"import data from line structured JSON"`
	PubKeyCmd        *PubKey        `arg:"subcommand:pubkey" json:"-" help:"print relay canister public key"`
	AddRelayCmd      *AddRelay      `arg:"subcommand:addrelay" json:"-" help:"add a relay to the cluster"`
	RemoveRelayCmd   *RemoveRelay   `arg:"subcommand:removerelay" json:"-" help:"remove a relay from the cluster"`
	GetPermissionCmd *GetPermission `arg:"subcommand:getpermission" json:"-" help:"get permission of a relay"`
	Wipe             *WipeBDB       `arg:"subcommand:wipebdb" json:"-" help:"empties local badger database (bdb)"`
	// Rescan           *RescanAC      `arg:"subcommand:rescan" json:"-" help:"clear and regenerate access counter records"`
	Listen       []string `arg:"-l,--listen,separate" json:"listen" help:"network address to listen on"`
	EventStore   string   `arg:"-e,--eventstore" json:"eventstore" help:"select event store backend [ic,badger,iconly]"`
	CanisterAddr string   `` /* 126-byte string literal not displayed */
	CanisterId   string   `arg:"-I,--canisterid" json:"canister_id" help:"IC canister ID to use"`
	Profile      string   `arg:"-p,--profile" default:"replicatr" json:"-"  help:"profile name to use for storage"` // default:"replicatr"
	Name         string   `arg:"-n,--name" json:"name"  help:"name of relay for NIP-11"`                            // default:"replicatr relay"
	Description  string   `arg:"-d,--description" json:"description" help:"description of relay for NIP-11"`
	Pubkey       string   `arg:"--pubkey" json:"pubkey" help:"public key of relay operator"`
	Contact      string   `arg:"-c,--contact" json:"contact,omitempty" help:"non-nostr relay operator contact details"`
	Icon         string   `arg:"-i,--icon" json:"icon"  help:"icon to show on relay information pages"`                // default:"https://i.nostr.build/n8vM.png"
	AuthRequired bool     `arg:"-a,--auth" json:"auth_required"  help:"NIP-42 authentication required for all access"` // default:"false"
	Public       bool     `arg:"--public" json:"public"  help:"allow public read access to users not on ACL"`          // default:"true"
	Owners       []string `arg:"-o,--owner,separate" json:"owners" help:"specify public keys of users with owner level permissions on relay"`
	SecKey       string   `` /* 131-byte string literal not displayed */
	// Whitelist permits ONLY inbound connections from specified IP addresses.
	Whitelist []string `arg:"-w,--whitelist,separate" json:"ip_whitelist" help:"IP addresses that are only allowed to access"`
	// AllowIPs is for bypassing authentication required for clients based on IP
	// addresses... primarily for testing with wireguard VPN clients run by the
	// developer, as these are stable, non-routeable addresses, this skips the
	// requirement enforced by AuthRequired.
	AllowIPs []string `arg:"-A,--allow,separate" json:"allow_ip" help:"IP addresses that are always allowed to access"`
	// DBSizeLimit configures a target maximum size to maintain the local
	// event store cache at, in megabytes (1,000,000 bytes).
	DBSizeLimit int `arg:"-S,--sizelimit" json:"db_size_limit" help:"set the maximum size of the badger event store in bytes"` // default:"0"
	// DBLowWater is the proportion of the DBSizeLimit to prune the database
	// down to when performing a garbage collection run.
	DBLowWater int `arg:"-L,--lowwater" json:"db_low_water" help:"set target percentage for database size during garbage collection"` // default:"86"
	// DBHighWater is the proportion of the DBSizeLimit at which a garbage
	// collection run is triggered.
	DBHighWater int `` // default:"92"
	/* 134-byte string literal not displayed */
	// GCFrequency is the frequency to run a check on the database size and
	// if it breaches DBHighWater to prune it back to DBLowWater percentage
	// of DBSizeLimit in minutes.
	GCFrequency int    `arg:"-G,--gcfreq" json:"gc_frequency" help:"frequency in seconds to check if database needs garbage collection"`            // default:"300"
	MaxProcs    int    `arg:"--maxprocs" json:"max_procs" help:"maximum number of goroutines to use"`                                               // default:"128"
	LogLevel    string `arg:"--loglevel"  help:"set log level [off,fatal,error,warn,info,debug,trace] (can also use GODEBUG environment variable)"` // default:"info"
	PProf       bool   `arg:"--pprof" help:"enable CPU and memory profiling"`
	GCRatio     int    `arg:"--gcratio" help:"set GC percentage for triggering GC sweeps"`             // default:"100"
	MemLimit    int64  `arg:"--memlimit" help:"set memory limit on process to constrain memory usage"` // default:"500000000"
	// PollFrequency is how often the L2 is queried for recent events
	PollFrequency time.Duration `arg:"--pollfrequency" help:"if a level 2 event store is enabled how often it polls"`
	// PollOverlap is the multiple of the PollFrequency within which polling the L2
	// is done to ensure any slow synchrony on the L2 is covered (2-4 usually)
	PollOverlap timestamp.T `arg:"--polloverlap" help:"if a level 2 event store is enabled, multiple of poll freq overlap to account for latency"`
}

func GetDefaultConfig

func GetDefaultConfig() *Config

func (*Config) Load

func (c *Config) Load(filename string) (err error)

func (*Config) Save

func (c *Config) Save(filename string) (err error)

type ExportCmd

type ExportCmd struct {
	ToFile string `arg:"-f,--tofile" help:"write to file instead of stdout"`
}

type GetPermission

type GetPermission struct {
}

type ImportCmd

type ImportCmd struct {
	FromFile     []string `arg:"-f,--fromfile,separate" help:"read from files instead of stdin (can use flag repeatedly for multiple files)"`
	StartingFrom int      `arg:"--importfrom" help:"start scanning import file from this position in bytes"`
}

type InitCfg

type InitCfg struct{}

type PubKey

type PubKey struct{}

type RemoveRelay

type RemoveRelay struct {
	PubKey string `arg:"--removepubkey" help:"public key of client to remove"`
}

type RescanAC

type RescanAC struct{}

type WipeBDB

type WipeBDB struct{}