using.rst.txt
1 .. _using-main: 2 3 ****************************** 4 Using Reticulum on Your System 5 ****************************** 6 7 Reticulum is not installed as a driver or kernel module, as one might expect 8 of a networking stack. Instead, Reticulum is distributed as a Python module, 9 containing the networking core, and a set of utility and daemon programs. 10 11 This means that no special privileges are required to install or use it. It 12 is also very light-weight, and easy to transfer to, and install on new systems. 13 14 When you have Reticulum installed, any program or application that uses Reticulum 15 will automatically load and initialise Reticulum when it starts, if it is not 16 already running. 17 18 In many cases, this approach is sufficient. When any program needs to use 19 Reticulum, it is loaded, initialised, interfaces are brought up, and the 20 program can now communicate over any Reticulum networks available. If another 21 program starts up and also wants access to the same Reticulum network, the already 22 running instance is simply shared. This works for any number of programs running 23 concurrently, and is very easy to use, but depending on your use case, there 24 are other options. 25 26 Configuration & Data 27 -------------------- 28 29 Reticulum stores all information that it needs to function in a single file-system 30 directory. When Reticulum is started, it will look for a valid configuration 31 directory in the following places: 32 33 - ``/etc/reticulum`` 34 - ``~/.config/reticulum`` 35 - ``~/.reticulum`` 36 37 If no existing configuration directory is found, the directory ``~/.reticulum`` 38 is created, and the default configuration will be automatically created here. 39 You can move it to one of the other locations if you wish. 40 41 It is also possible to use completely arbitrary configuration directories by 42 specifying the relevant command-line parameters when running Reticulum-based 43 programs. You can also run multiple separate Reticulum instances on the same 44 physical system, either in isolation from each other, or connected together. 45 46 In most cases, a single physical system will only need to run one Reticulum 47 instance. This can either be launched at boot, as a system service, or simply 48 be brought up when a program needs it. In either case, any number of programs 49 running on the same system will automatically share the same Reticulum instance, 50 if the configuration allows for it, which it does by default. 51 52 The entire configuration of Reticulum is found in the ``~/.reticulum/config`` 53 file. When Reticulum is first started on a new system, a basic, but fully functional 54 configuration file is created. The default configuration looks like this: 55 56 .. code:: 57 58 # This is the default Reticulum config file. 59 # You should probably edit it to include any additional, 60 # interfaces and settings you might need. 61 62 # Only the most basic options are included in this default 63 # configuration. To see a more verbose, and much longer, 64 # configuration example, you can run the command: 65 # rnsd --exampleconfig 66 67 68 [reticulum] 69 70 # If you enable Transport, your system will route traffic 71 # for other peers, pass announces and serve path requests. 72 # This should be done for systems that are suited to act 73 # as transport nodes, ie. if they are stationary and 74 # always-on. This directive is optional and can be removed 75 # for brevity. 76 77 enable_transport = No 78 79 80 # By default, the first program to launch the Reticulum 81 # Network Stack will create a shared instance, that other 82 # programs can communicate with. Only the shared instance 83 # opens all the configured interfaces directly, and other 84 # local programs communicate with the shared instance over 85 # a local socket. This is completely transparent to the 86 # user, and should generally be turned on. This directive 87 # is optional and can be removed for brevity. 88 89 share_instance = Yes 90 91 92 # If you want to run multiple *different* shared instances 93 # on the same system, you will need to specify different 94 # instance names for each. On platforms supporting domain 95 # sockets, this can be done with the instance_name option: 96 97 instance_name = default 98 99 # Some platforms don't support domain sockets, and if that 100 # is the case, you can isolate different instances by 101 # specifying a unique set of ports for each: 102 103 # shared_instance_port = 37428 104 # instance_control_port = 37429 105 106 107 # If you want to explicitly use TCP for shared instance 108 # communication, instead of domain sockets, this is also 109 # possible, by using the following option: 110 111 # shared_instance_type = tcp 112 113 114 # On systems where running instances may not have access 115 # to the same shared Reticulum configuration directory, 116 # it is still possible to allow full interactivity for 117 # running instances, by manually specifying a shared RPC 118 # key. In almost all cases, this option is not needed, but 119 # it can be useful on operating systems such as Android. 120 # The key must be specified as bytes in hexadecimal. 121 122 # rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790 123 124 125 # It is possible to allow remote management of Reticulum 126 # systems using the various built-in utilities, such as 127 # rnstatus and rnpath. You will need to specify one or 128 # more Reticulum Identity hashes for authenticating the 129 # queries from client programs. For this purpose, you can 130 # use existing identity files, or generate new ones with 131 # the rnid utility. 132 133 # enable_remote_management = yes 134 # remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc 135 136 137 # You can configure Reticulum to panic and forcibly close 138 # if an unrecoverable interface error occurs, such as the 139 # hardware device for an interface disappearing. This is 140 # an optional directive, and can be left out for brevity. 141 # This behaviour is disabled by default. 142 143 # panic_on_interface_error = No 144 145 146 # When Transport is enabled, it is possible to allow the 147 # Transport Instance to respond to probe requests from 148 # the rnprobe utility. This can be a useful tool to test 149 # connectivity. When this option is enabled, the probe 150 # destination will be generated from the Identity of the 151 # Transport Instance, and printed to the log at startup. 152 # Optional, and disabled by default. 153 154 # respond_to_probes = No 155 156 157 [logging] 158 # Valid log levels are 0 through 7: 159 # 0: Log only critical information 160 # 1: Log errors and lower log levels 161 # 2: Log warnings and lower log levels 162 # 3: Log notices and lower log levels 163 # 4: Log info and lower (this is the default) 164 # 5: Verbose logging 165 # 6: Debug logging 166 # 7: Extreme logging 167 168 loglevel = 4 169 170 171 # The interfaces section defines the physical and virtual 172 # interfaces Reticulum will use to communicate on. This 173 # section will contain examples for a variety of interface 174 # types. You can modify these or use them as a basis for 175 # your own config, or simply remove the unused ones. 176 177 [interfaces] 178 179 # This interface enables communication with other 180 # link-local Reticulum nodes over UDP. It does not 181 # need any functional IP infrastructure like routers 182 # or DHCP servers, but will require that at least link- 183 # local IPv6 is enabled in your operating system, which 184 # should be enabled by default in almost any OS. See 185 # the Reticulum Manual for more configuration options. 186 187 [[Default Interface]] 188 type = AutoInterface 189 interface_enabled = True 190 191 If Reticulum infrastructure already exists locally, you probably don't need to 192 change anything, and you may already be connected to a wider network. If not, 193 you will probably need to add relevant *interfaces* to the configuration, in 194 order to communicate with other systems. 195 196 You can generate a much more verbose configuration example by running the command: 197 198 ``rnsd --exampleconfig`` 199 200 The output includes examples for most interface types supported 201 by Reticulum, along with additional options and configuration parameters. 202 203 It is a good idea to read the comments and explanations in the above default config. 204 It will teach you the basic concepts you need to understand to configure your network. 205 Once you have done that, take a look at the :ref:`Interfaces<interfaces-main>` chapter 206 of this manual. 207 208 Included Utility Programs 209 ------------------------- 210 211 Reticulum includes a range of useful utilities, both for managing your Reticulum 212 networks, and for carrying out common tasks over Reticulum networks, such as 213 transferring files to remote systems, and executing commands and programs remotely. 214 215 If you often use Reticulum from several different programs, or simply want 216 Reticulum to stay available all the time, for example if you are hosting 217 a transport node, you might want to run Reticulum as a separate service that 218 other programs, applications and services can utilise. 219 220 The rnsd Utility 221 ================ 222 223 It is very easy to run Reticulum as a service. Simply run the included ``rnsd`` command. 224 When ``rnsd`` is running, it will keep all configured interfaces open, handle transport if 225 it is enabled, and allow any other programs to immediately utilise the 226 Reticulum network it is configured for. 227 228 You can even run multiple instances of ``rnsd`` with different configurations on 229 the same system. 230 231 **Usage Examples** 232 233 Run ``rnsd``: 234 235 .. code:: text 236 237 $ rnsd 238 239 [2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8 240 241 Run ``rnsd`` in service mode, ensuring all logging output is sent directly to file: 242 243 .. code:: text 244 245 $ rnsd -s 246 247 Generate a verbose and detailed configuration example, with explanations of all the 248 various configuration options, and interface configuration examples: 249 250 .. code:: text 251 252 $ rnsd --exampleconfig 253 254 **All Command-Line Options** 255 256 .. code:: text 257 258 usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version] 259 260 Reticulum Network Stack Daemon 261 262 options: 263 -h, --help show this help message and exit 264 --config CONFIG path to alternative Reticulum config directory 265 -v, --verbose 266 -q, --quiet 267 -s, --service rnsd is running as a service and should log to file 268 --exampleconfig print verbose configuration example to stdout and exit 269 --version show program's version number and exit 270 271 You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`. 272 273 The rnstatus Utility 274 ==================== 275 276 Using the ``rnstatus`` utility, you can view the status of configured Reticulum 277 interfaces, similar to the ``ifconfig`` program. 278 279 **Usage Examples** 280 281 Run ``rnstatus``: 282 283 .. code:: text 284 285 $ rnstatus 286 287 Shared Instance[37428] 288 Status : Up 289 Serving : 1 program 290 Rate : 1.00 Gbps 291 Traffic : 83.13 KB↑ 292 86.10 KB↓ 293 294 AutoInterface[Local] 295 Status : Up 296 Mode : Full 297 Rate : 10.00 Mbps 298 Peers : 1 reachable 299 Traffic : 63.23 KB↑ 300 80.17 KB↓ 301 302 TCPInterface[RNS Testnet Dublin/dublin.connect.reticulum.network:4965] 303 Status : Up 304 Mode : Full 305 Rate : 10.00 Mbps 306 Traffic : 187.27 KB↑ 307 74.17 KB↓ 308 309 RNodeInterface[RNode UHF] 310 Status : Up 311 Mode : Access Point 312 Rate : 1.30 kbps 313 Access : 64-bit IFAC by <…e702c42ba8> 314 Traffic : 8.49 KB↑ 315 9.23 KB↓ 316 317 Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running 318 319 Filter output to only show some interfaces: 320 321 .. code:: text 322 323 $ rnstatus rnode 324 325 RNodeInterface[RNode UHF] 326 Status : Up 327 Mode : Access Point 328 Rate : 1.30 kbps 329 Access : 64-bit IFAC by <…e702c42ba8> 330 Traffic : 8.49 KB↑ 331 9.23 KB↓ 332 333 Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running 334 335 **All Command-Line Options** 336 337 .. code:: text 338 339 usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-A] 340 [-l] [-s SORT] [-r] [-j] [-R hash] [-i path] 341 [-w seconds] [-v] [filter] 342 343 Reticulum Network Stack Status 344 345 positional arguments: 346 filter only display interfaces with names including filter 347 348 options: 349 -h, --help show this help message and exit 350 --config CONFIG path to alternative Reticulum config directory 351 --version show program's version number and exit 352 -a, --all show all interfaces 353 -A, --announce-stats show announce stats 354 -l, --link-stats show link stats 355 -s SORT, --sort SORT sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held] 356 -r, --reverse reverse sorting 357 -j, --json output in JSON format 358 -R hash transport identity hash of remote instance to get status from (requires -i) 359 -i path path to identity used for remote management 360 -w seconds timeout before giving up on remote queries 361 -v, --verbose 362 363 364 .. note:: 365 When using ``-R`` to query a remote transport instance, you must also specify ``-i`` with the path to a management identity file that is authorized for remote management on the target system. 366 367 The rnid Utility 368 ==================== 369 370 With the ``rnid`` utility, you can generate, manage and view Reticulum Identities. 371 The program can also calculate Destination hashes, and perform encryption and 372 decryption of files. 373 374 Using ``rnid``, it is possible to asymmetrically encrypt files and information for 375 any Reticulum destination hash, and also to create and verify cryptographic signatures. 376 377 **Usage Examples** 378 379 Generate a new Identity: 380 381 .. code:: text 382 383 $ rnid -g ./new_identity 384 385 Display Identity key information: 386 387 .. code:: text 388 389 $ rnid -i ./new_identity -p 390 391 Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id 392 Public Key : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e 393 Private Key : Hidden 394 395 Encrypt a file for an LXMF user: 396 397 .. code:: text 398 399 $ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt 400 401 Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695> 402 Encrypting my_file.txt 403 File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe 404 405 If the Identity for the destination is not already known, you can fetch it from the network by using the ``-R`` command-line option: 406 407 .. code:: text 408 409 $ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt 410 411 Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>... 412 Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network 413 Encrypting my_file.txt 414 File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe 415 416 Decrypt a file using the Reticulum Identity it was encrypted for: 417 418 .. code:: text 419 420 $ rnid -i ./my_identity -d my_file.txt.rfe 421 422 Loaded Identity <2225fdeecaf6e2db4556c3c2d7637294> from ./my_identity 423 Decrypting ./my_file.txt.rfe... 424 File ./my_file.txt.rfe decrypted with <2225fdeecaf6e2db4556c3c2d7637294> to ./my_file.txt 425 426 **All Command-Line Options** 427 428 .. code:: text 429 430 usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] 431 [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] 432 [-f] [-R] [-t seconds] [-p] [-P] [--version] 433 434 Reticulum Identity & Encryption Utility 435 436 options: 437 -h, --help show this help message and exit 438 --config path path to alternative Reticulum config directory 439 -i identity, --identity identity 440 hexadecimal Reticulum Destination hash or path to Identity file 441 -g path, --generate path 442 generate a new Identity 443 -v, --verbose increase verbosity 444 -q, --quiet decrease verbosity 445 -a aspects, --announce aspects 446 announce a destination based on this Identity 447 -H aspects, --hash aspects 448 show destination hashes for other aspects for this Identity 449 -e path, --encrypt path 450 encrypt file 451 -d path, --decrypt path 452 decrypt file 453 -s path, --sign path sign file 454 -V path, --validate path 455 validate signature 456 -r path, --read path input file path 457 -w path, --write path 458 output file path 459 -f, --force write output even if it overwrites existing files 460 -R, --request request unknown Identities from the network 461 -t seconds identity request timeout before giving up 462 -p, --print-identity print identity info and exit 463 -P, --print-private allow displaying private keys 464 --version show program's version number and exit 465 466 467 The rnpath Utility 468 ==================== 469 470 With the ``rnpath`` utility, you can look up and view paths for 471 destinations on the Reticulum network. 472 473 **Usage Examples** 474 475 Resolve path to a destination: 476 477 .. code:: text 478 479 $ rnpath c89b4da064bf66d280f0e4d8abfd9806 480 481 Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965] 482 483 **All Command-Line Options** 484 485 .. code:: text 486 487 usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops] 488 [-r] [-d] [-D] [-x] [-w seconds] [-R hash] [-i path] 489 [-W seconds] [-j] [-v] [destination] 490 491 Reticulum Path Discovery Utility 492 493 positional arguments: 494 destination hexadecimal hash of the destination 495 496 options: 497 -h, --help show this help message and exit 498 --config CONFIG path to alternative Reticulum config directory 499 --version show program's version number and exit 500 -t, --table show all known paths 501 -m hops, --max hops maximum hops to filter path table by 502 -r, --rates show announce rate info 503 -d, --drop remove the path to a destination 504 -D, --drop-announces drop all queued announces 505 -x, --drop-via drop all paths via specified transport instance 506 -w seconds timeout before giving up 507 -R hash transport identity hash of remote instance to manage 508 -i path path to identity used for remote management 509 -W seconds timeout before giving up on remote queries 510 -j, --json output in JSON format 511 -v, --verbose 512 513 514 The rnprobe Utility 515 ==================== 516 517 The ``rnprobe`` utility lets you probe a destination for connectivity, similar 518 to the ``ping`` program. Please note that probes will only be answered if the 519 specified destination is configured to send proofs for received packets. Many 520 destinations will not have this option enabled, so most destinations will not 521 be probable. 522 523 You can enable a probe-reply destination on Reticulum Transport Instances by 524 setting the ``respond_to_probes`` configuration directive. Reticulum will then 525 print the probe destination to the log on Transport Instance startup. 526 527 **Usage Examples** 528 529 Probe a destination: 530 531 .. code:: text 532 533 $ rnprobe rnstransport.probe 2d03725b327348980d570f739a3a5708 534 535 Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> 536 Valid reply received from <2d03725b327348980d570f739a3a5708> 537 Round-trip time is 38.469 milliseconds over 2 hops 538 539 Send a larger probe: 540 541 .. code:: text 542 543 $ rnprobe rnstransport.probe 2d03725b327348980d570f739a3a5708 -s 256 544 545 Sent 16 byte probe to <2d03725b327348980d570f739a3a5708> 546 Valid reply received from <2d03725b327348980d570f739a3a5708> 547 Round-trip time is 38.781 milliseconds over 2 hops 548 549 If the interface that receives the probe replies supports reporting radio 550 parameters such as **RSSI** and **SNR**, the ``rnprobe`` utility will print 551 these as part of the result as well. 552 553 .. code:: text 554 555 $ rnprobe rnstransport.probe e7536ee90bd4a440e130490b87a25124 556 557 Sent 16 byte probe to <e7536ee90bd4a440e130490b87a25124> 558 Valid reply received from <e7536ee90bd4a440e130490b87a25124> 559 Round-trip time is 1.809 seconds over 1 hop [RSSI -73 dBm] [SNR 12.0 dB] 560 561 **All Command-Line Options** 562 563 .. code:: text 564 565 usage: rnprobe [-h] [--config CONFIG] [-s SIZE] [-n PROBES] 566 [-t seconds] [-w seconds] [--version] [-v] 567 [full_name] [destination_hash] 568 569 Reticulum Probe Utility 570 571 positional arguments: 572 full_name full destination name in dotted notation 573 destination_hash hexadecimal hash of the destination 574 575 options: 576 -h, --help show this help message and exit 577 --config CONFIG path to alternative Reticulum config directory 578 -s SIZE, --size SIZE size of probe packet payload in bytes 579 -n PROBES, --probes PROBES 580 number of probes to send 581 -t seconds, --timeout seconds 582 timeout before giving up 583 -w seconds, --wait seconds 584 time between each probe 585 --version show program's version number and exit 586 -v, --verbose 587 588 589 The rncp Utility 590 ================ 591 592 The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer 593 files through Reticulum. 594 595 **Usage Examples** 596 597 Run rncp on the receiving system, specifying which identities are allowed to send files: 598 599 .. code:: text 600 601 $ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62 602 603 You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities 604 and simply running the program in listener mode: 605 606 .. code:: text 607 608 $ rncp --listen 609 610 From another system, copy a file to the receiving system: 611 612 .. code:: text 613 614 $ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e 615 616 Or fetch a file from the remote system: 617 618 .. code:: text 619 620 $ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e 621 622 **All Command-Line Options** 623 624 .. code:: text 625 626 usage: rncp [-h] [--config path] [-v] [-q] [-S] [-l] [-F] [-f] 627 [-j path] [-b seconds] [-a allowed_hash] [-n] [-p] 628 [-w seconds] [--version] [file] [destination] 629 630 Reticulum File Transfer Utility 631 632 positional arguments: 633 file file to be transferred 634 destination hexadecimal hash of the receiver 635 636 options: 637 -h, --help show this help message and exit 638 --config path path to alternative Reticulum config directory 639 -v, --verbose increase verbosity 640 -q, --quiet decrease verbosity 641 -S, --silent disable transfer progress output 642 -l, --listen listen for incoming transfer requests 643 -F, --allow-fetch allow authenticated clients to fetch files 644 -f, --fetch fetch file from remote listener instead of sending 645 -j path, --jail path restrict fetch requests to specified path 646 -b seconds announce interval, 0 to only announce at startup 647 -a allowed_hash allow this identity 648 -n, --no-auth accept requests from anyone 649 -p, --print-identity print identity and destination info and exit 650 -w seconds sender timeout before giving up 651 --version show program's version number and exit 652 653 654 The rnx Utility 655 ================ 656 657 The ``rnx`` utility is a basic remote command execution program. It allows you to 658 execute commands on remote systems over Reticulum, and to view returned command 659 output. For a fully interactive remote shell solution, be sure to also take a look 660 at the `rnsh <https://github.com/acehoss/rnsh>`_ program. 661 662 **Usage Examples** 663 664 Run rnx on the listening system, specifying which identities are allowed to execute commands: 665 666 .. code:: text 667 668 $ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10 669 670 From another system, run a command on the remote: 671 672 .. code:: text 673 674 $ rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo" 675 676 Or enter the interactive mode pseudo-shell: 677 678 .. code:: text 679 680 $ rnx 7a55144adf826958a9529a3bcf08b149 -x 681 682 The default identity file is stored in ``~/.reticulum/identities/rnx``, but you can use 683 another one, which will be created if it does not already exist 684 685 .. code:: text 686 687 $ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x 688 689 **All Command-Line Options** 690 691 .. code:: text 692 693 usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N] 694 [-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN] 695 [--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command] 696 697 Reticulum Remote Execution Utility 698 699 positional arguments: 700 destination hexadecimal hash of the listener 701 command command to be execute 702 703 optional arguments: 704 -h, --help show this help message and exit 705 --config path path to alternative Reticulum config directory 706 -v, --verbose increase verbosity 707 -q, --quiet decrease verbosity 708 -p, --print-identity print identity and destination info and exit 709 -l, --listen listen for incoming commands 710 -i identity path to identity to use 711 -x, --interactive enter interactive mode 712 -b, --no-announce don't announce at program start 713 -a allowed_hash accept from this identity 714 -n, --noauth accept files from anyone 715 -N, --noid don't identify to listener 716 -d, --detailed show detailed result output 717 -m mirror exit code of remote command 718 -w seconds connect and request timeout before giving up 719 -W seconds max result download time 720 --stdin STDIN pass input to stdin 721 --stdout STDOUT max size in bytes of returned stdout 722 --stderr STDERR max size in bytes of returned stderr 723 --version show program's version number and exit 724 725 726 The rnodeconf Utility 727 ===================== 728 729 The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and 730 to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices. 731 732 **All Command-Line Options** 733 734 .. code:: text 735 736 usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] 737 [--fw-url url] [--nocheck] [-e] [-E] [-C] 738 [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i] 739 [--display-addr byte] [--freq Hz] [--bw Hz] [--txp dBm] 740 [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] 741 [--eeprom-wipe] [-P] [--trust-key hexbytes] [--version] [-f] 742 [-r] [-k] [-S] [-H FIRMWARE_HASH] [--platform platform] 743 [--product product] [--model model] [--hwrev revision] 744 [port] 745 746 RNode Configuration and firmware utility. This program allows you to change 747 various settings and startup modes of RNode. It can also install, flash and 748 update the firmware on supported devices. 749 750 positional arguments: 751 port serial port where RNode is attached 752 753 options: 754 -h, --help show this help message and exit 755 -i, --info Show device info 756 -a, --autoinstall Automatic installation on various supported devices 757 -u, --update Update firmware to the latest version 758 -U, --force-update Update to specified firmware even if version matches 759 or is older than installed version 760 --fw-version version Use a specific firmware version for update or 761 autoinstall 762 --fw-url url Use an alternate firmware download URL 763 --nocheck Don't check for firmware updates online 764 -e, --extract Extract firmware from connected RNode for later use 765 -E, --use-extracted Use the extracted firmware for autoinstallation or 766 update 767 -C, --clear-cache Clear locally cached firmware files 768 --baud-flash baud_flash 769 Set specific baud rate when flashing device. Default 770 is 921600 771 -N, --normal Switch device to normal mode 772 -T, --tnc Switch device to TNC mode 773 -b, --bluetooth-on Turn device bluetooth on 774 -B, --bluetooth-off Turn device bluetooth off 775 -p, --bluetooth-pair Put device into bluetooth pairing mode 776 -D i, --display i Set display intensity (0-255) 777 --display-addr byte Set display address as hex byte (00 - FF) 778 --freq Hz Frequency in Hz for TNC mode 779 --bw Hz Bandwidth in Hz for TNC mode 780 --txp dBm TX power in dBm for TNC mode 781 --sf factor Spreading factor for TNC mode (7 - 12) 782 --cr rate Coding rate for TNC mode (5 - 8) 783 --eeprom-backup Backup EEPROM to file 784 --eeprom-dump Dump EEPROM to console 785 --eeprom-wipe Unlock and wipe EEPROM 786 -P, --public Display public part of signing key 787 --trust-key hexbytes Public key to trust for device verification 788 --version Print program version and exit 789 -f, --flash Flash firmware and bootstrap EEPROM 790 -r, --rom Bootstrap EEPROM without flashing firmware 791 -k, --key Generate a new signing key and exit 792 -S, --sign Display public part of signing key 793 -H FIRMWARE_HASH, --firmware-hash FIRMWARE_HASH 794 Display installed firmware hash 795 --platform platform Platform specification for device bootstrap 796 --product product Product specification for device bootstrap 797 --model model Model code for device bootstrap 798 --hwrev revision Hardware revision for device bootstrap 799 800 801 For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>` 802 section of this manual. 803 804 Remote Management 805 ----------------- 806 807 It is possible to allow remote management of Reticulum 808 systems using the various built-in utilities, such as 809 ``rnstatus`` and ``rnpath``. To do so, you will need to set 810 the ``enable_remote_management`` directive in the ``[reticulum]`` 811 section of the configuration file. You will also need to specify 812 one or more Reticulum Identity hashes for authenticating the 813 queries from client programs. For this purpose, you can use 814 existing identity files, or generate new ones with the rnid utility. 815 816 The following is a truncated example of enabling remote management 817 in the Reticulum configuration file: 818 819 .. code:: text 820 821 [reticulum] 822 ... 823 enable_remote_management = yes 824 remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc 825 ... 826 827 For a complete example configuration, you can run ``rnsd --exampleconfig``. 828 829 Improving System Configuration 830 ------------------------------ 831 832 If you are setting up a system for permanent use with Reticulum, there is a 833 few system configuration changes that can make this easier to administrate. 834 These changes will be detailed here. 835 836 837 Fixed Serial Port Names 838 ======================= 839 840 On a Reticulum instance with several serial port based interfaces, it can be 841 beneficial to use the fixed device names for the serial ports, instead 842 of the dynamically allocated shorthands such as ``/dev/ttyUSB0``. Under most 843 Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes 844 can be found under ``/dev/serial/by-id``. 845 846 You can use such a device path directly in place of the numbered shorthands. 847 Here is an example of a packet radio TNC configured as such: 848 849 .. code:: text 850 851 [[Packet Radio KISS Interface]] 852 type = KISSInterface 853 interface_enabled = True 854 outgoing = true 855 port = /dev/serial/by-id/usb-FTDI_FT230X_Basic_UART_43891CKM-if00-port0 856 speed = 115200 857 databits = 8 858 parity = none 859 stopbits = 1 860 preamble = 150 861 txtail = 10 862 persistence = 200 863 slottime = 20 864 865 Using this methodology avoids potential naming mix-ups where physical devices 866 might be plugged and unplugged in different orders, or when device name 867 assignment varies from one boot to another. 868 869 .. _using-systemd: 870 871 Reticulum as a System Service 872 ============================= 873 874 Instead of starting Reticulum manually, you can install ``rnsd`` as a system 875 service and have it start automatically at boot. 876 877 Systemwide Service 878 ^^^^^^^^^^^^^^^^^^ 879 880 If you installed Reticulum with ``pip``, the ``rnsd`` program will most likely 881 be located in a user-local installation path only, which means ``systemd`` will not 882 be able to execute it. In this case, you can simply symlink the ``rnsd`` program 883 into a directory that is in systemd's path: 884 885 .. code:: text 886 887 sudo ln -s $(which rnsd) /usr/local/bin/ 888 889 You can then create the service file ``/etc/systemd/system/rnsd.service`` with the 890 following content: 891 892 .. code:: text 893 894 [Unit] 895 Description=Reticulum Network Stack Daemon 896 After=multi-user.target 897 898 [Service] 899 # If you run Reticulum on WiFi devices, 900 # or other devices that need some extra 901 # time to initialise, you might want to 902 # add a short delay before Reticulum is 903 # started by systemd: 904 # ExecStartPre=/bin/sleep 10 905 Type=simple 906 Restart=always 907 RestartSec=3 908 User=USERNAMEHERE 909 ExecStart=rnsd --service 910 911 [Install] 912 WantedBy=multi-user.target 913 914 Be sure to replace ``USERNAMEHERE`` with the user you want to run ``rnsd`` as. 915 916 To manually start ``rnsd`` run: 917 918 .. code:: text 919 920 sudo systemctl start rnsd 921 922 If you want to automatically start ``rnsd`` at boot, run: 923 924 .. code:: text 925 926 sudo systemctl enable rnsd 927 928 Userspace Service 929 ^^^^^^^^^^^^^^^^^ 930 931 Alternatively you can use a user systemd service instead of a system wide one. This way the whole setup can be done as a regular user. 932 Create a user systemd service files ``~/.config/systemd/user/rnsd.service`` with the following content: 933 934 .. code:: text 935 936 [Unit] 937 Description=Reticulum Network Stack Daemon 938 After=default.target 939 940 [Service] 941 # If you run Reticulum on WiFi devices, 942 # or other devices that need some extra 943 # time to initialise, you might want to 944 # add a short delay before Reticulum is 945 # started by systemd: 946 # ExecStartPre=/bin/sleep 10 947 Type=simple 948 Restart=always 949 RestartSec=3 950 ExecStart=RNS_BIN_DIR/rnsd --service 951 952 [Install] 953 WantedBy=default.target 954 955 Replace ``RNS_BIN_DIR`` with the path to your Reticulum binary directory (eg. /home/USERNAMEHERE/rns/bin). 956 957 Start user service: 958 959 .. code:: text 960 961 systemctl --user daemon-reload 962 systemctl --user start rnsd.service 963 964 If you want to automatically start ``rnsd`` without having to log in as the USERNAMEHERE, do: 965 966 .. code:: text 967 968 sudo loginctl enable-linger USERNAMEHERE 969 systemctl --user enable rnsd.service 970 971