Skip to content

System controls

The pmesh API exposes a number of endpoints to manage the state of the server, as well as the entire mesh.

Ping | /ping

Returns a simple pong response, with the hostname of this machine.

Terminal window
$ curl http://pm3/ping
"myhostname"

Shutdown | /shutdown

Shuts down the server.

Terminal window
$ curl http://pm3/shutdown
{}

PMesh Revision | /version

Returns information about the current version of the pmesh server. The result is a string with the current version.

Terminal window
$ curl http://pm3/version?pretty
"v0.3-122fca54"

System metrics | /system

Returns a map of system metrics.

The result is an object with the following structure:

ResultTypeDescription
machine_idstringThe machine ID.
cpu[N].cpunumberThe CPU number.
cpu[N].vendorIdstringThe CPU vendor ID.
cpu[N].familystringThe CPU family.
cpu[N].modelstringThe CPU model.
cpu[N].steppingnumberThe CPU stepping.
cpu[N].physicalIdstringThe CPU physical ID.
cpu[N].coreIdstringThe CPU core ID.
cpu[N].coresnumberThe number of CPU cores.
cpu[N].modelNamestringThe CPU model name.
cpu[N].mhznumberThe CPU speed in MHz.
cpu[N].cacheSizenumberThe CPU cache size.
cpu[N].flagsarrayThe CPU flags.
cpu[N].microcodestringThe CPU microcode.
loadnumberThe system load.
rxnumberThe received network traffic in bytes per second.
txnumberThe transmitted network traffic in bytes per second.
freedisknumberThe free disk space in bytes.
freememnumberThe free memory in bytes.
totaldisknumberThe total disk space in bytes.
totalmemnumberThe total memory in bytes.
uptimenumberThe system uptime in seconds.
hostnamestringThe hostname of the machine.
uidstringThe unique machine ID.
process_countnumberThe number of running processes.
osstringThe operating system.
kernel_versionstringThe kernel version.
kernel_archstringThe kernel architecture.
virtualization_systemstringThe virtualization system.
virtualization_rolestringThe virtualization role.
rtt[mach]numberThe round-trip time to the remote machine, in milliseconds.
Terminal window
$ curl http://pm3/system?pretty
{
"machine_id": "abcd1234",
"cpu": {
"cpu": 0,
"vendorId": "ARM",
"family": "",
"model": "0xd0c",
"stepping": 1,
"physicalId": "",
"coreId": "4608",
"cores": 80,
"modelName": "Neoverse-N1",
"mhz": 3000,
"cacheSize": 0,
"flags": [
"fp",
"asimd",
"evtstrm",
"aes",
"pmull",
"sha1",
"sha2",
"crc32",
"atomics",
"fphp",
"asimdhp",
"cpuid",
"asimdrdm",
"lrcpc",
"dcpop",
"asimddp",
"ssbs"
],
"microcode": ""
},
"load": 0.23767826036767198,
"rx": 68946.40320157344,
"tx": 358612.36113821046,
"freedisk": 1789967761408,
"freemem": 159653228544,
"totaldisk": 2127283216384,
"totalmem": 269258022912,
"uptime": 380589,
"hostname": "my hostname",
"uid": "00000000-0000-4000-8000-123456789abc",
"process_count": 786,
"os": "linux",
"kernel_version": "5.15.0-97-generic",
"kernel_arch": "aarch64",
"virtualization_system": "",
"virtualization_role": "",
"rtt": {
"abcd1234": 715.439607,
"abcd1235": 614.897263,
"abcd1236": -1, # not reachable
"abcd1237": 0.323401,
"abcd1238": 737.126561,
"abcd1239": 4.650896
}
}

Peer information | /peers & /peers/alive

Returns a list of all peers in the mesh, or only those that are currently alive, respectively.

The result is an array of the following object structure:

ResultTypeDescription
machine_idstringThe machine ID.
hoststringThe configured hostname.
ipstringAdvertised IP address
latnumberLatitude of geolocation.
lonnumberLongitude of geolocation.
countrystringGeolocated Country
ispstringISP
heartbeatnumberTimestamp of last heartbeat, milliseconds since epoch.
distancenumberDistance to this peer, in kilometers.
udmap[string]anyUser-defined data.
sdmap[string]anySystem-defined data.
mebooleanWhether this peer is the local machine.
Terminal window
$ curl http://pm3/peers?pretty
[
{
"machine_id": "abcd1234",
"host": "myhostname",
"ip": "xx.xx.xx.xx",
"lat": xx.xxxx,
"lon": xx.xxxx,
"country": "US",
"isp": "XX LTD",
"heartbeat": 1709951301935,
"me": true,
"distance": 0,
"ud": {},
"sd": {
"branch": "main",
"commit": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"services": [
"assets",
"my-api"
]
}
}
]