Networking

Overview

PeterOS uses a IP like system

Setup

Local setup

To set up a computer to access an existing network insure the computer has modem connected to the network (ie. ender modem to connect to wireless global network). Most programs automatic initialize the net module if it is not yet when they need it. However, you can do it manually by running net.init().

Once the computer has an IP address, it can then talk to any other computer on the network via the receiver's IP address, and to other networks via Network Address Transversal.

Dynamic IP assignment

Dynamic assignment is the default, and unless an IP is provided when initializing the module attempts one will be requested.

Static IP assignment

If you want (or need) to assign a static address to a computer, you can pass the address in numeric as the second parameter, ie. net.init(nil, address)

Warning

DNS functionality may not work with static IP assignment

Warning

When using static IP assignment, you are responsible for ensuring that every computer has a unique IP address

Global Network Setup

1) Network type

There are 2 types of global networks, wired, and wireless.

• Wireless global networks can be connected to without having to run new cabling to every computer or subnet, but requires ender modems.
• Wired networks on the other hand require a cable run to every computer, and prevents usage of pocket computers on the global network.

2) DHCP Server

For either type of network you need a Dynamic Host Configuration Protocol (DHCP) server.

In the default networking package there is a DHCP/DNS (Domain Name Service) server that can be used, found at /os/net/dhcp.lua. It can be used for both global networks and subnets, depending on configurations.

3) DHCP Config

The configuration file for the DHCP will be created at /home/dhcp.cfg and starts as the following

{
    "mask": 4294901760,
    "baseAddr": 3232235520,
    "addr": 3232235520,
    "addrTbl": {
        "defGateway": 3232235521,
        "dns": 3232235520,
    },
    "global": false,
    "adminPass": "admin"
}

See here for details

For global networks the config need to change to represent the global address space (0.0.0.0/8).

• mask needs to be set to 16777215 (0x00ffffff - 0.255.255.255)
• baseAddr, addr, and dns need to be set to 0 (0x000000 - 0.0.0.0)
• global needs to be set to true

In addition, it is recommend to change adminPass, as everyone may have access to the network, and could try the default password to maliciously set DNS records.

4) Adding DNS records

Once the network is up and running, you can domain name records to the server by going to 0.0.0.0 (or the value of addr in the config) in a browser and entering the admin password set in the config. Then navigate to the DNS page, and click the Add Record button. The fields are:

• Name: Record hostname, ie. xyz.com
• Host: IP address of computer hostname should be directed to
• Port: Port filter for DNS record, defaults to any port if left empty (Advisory only)

Records can be edited by creating a new record with the same hostname.

Subnet Setup

1) Network type

Generally, subnets can only be wired, however, if the global networks is wired you can have a wireless subnet. Each subnet can only be wired or wireless, but you could have a subnet within you subnet that was wireless.

2) NAT Setup

If the subnet should be connected to the global network, you need to have a Network Address Transversal (NAT) device between the subnet and global network (or higher level subnet).

In the default networking package there is a NAT server that can be used, found at /os/net/nat.lua.

3) NAT Config

The configuration file for the NAT will be created at /home/nat.cfg and starts as the following

{
    "inside": {
        "side": "right",
        "mask": 4294901760,
        "baseAddr": 3232235520,
        "addr": 3232235521
    },
    "outside": {
        "side": "left"
    }
}

See here for details

If your subnet is not 192.168.0.0/16 then you need to change mask, baseAddr, and addr appropriately. See the Reserved IP Addresses IPV4 table for private network address ranges.

Important

addr is the LOCAL address of the NAT, it will get it's global address from a global DHCP.

Note

If you are using multiple layers of subnets, make sure their address spaces don't overlap to avoid communication issues.

4) DHCP Server

In addition to the NAT you need a Dynamic Host Configuration Protocol (DHCP) server.

In the default networking package there is a DHCP/DNS (Domain Name Service) server that can be used, found at /os/net/dhcp.lua. It can be used for both global networks and subnets, depending on configurations.

5) DHCP Config

The configuration file for the DHCP will be created at /home/dhcp.cfg and starts as the following

{
    "mask": 4294901760,
    "baseAddr": 3232235520,
    "addr": 3232235520,
    "addrTbl": {
        "defGateway": 3232235521,
        "dns": 3232235520,
    },
    "global": false,
    "adminPass": "admin"
}

See here for details

If you are not using the default subnet address space of 192.168.0.0/16, you need to update the config.

• mask is the subnet mask, ie. for a subnet of 10.0.0.0/8 the mask would be would be 4278190080 (0xff000000 - 255.0.0.0)
• baseAddr, addr, and dns need to be set to the base address of the subnet (ie. 10.0.0.0 for subnet 10.0.0.0/8)
• defGateway needs to be set the the LOCAL address of the NAT (usually one higher than dns: for example 10.0.0.1)

In addition, it is recommend to change adminPass, as anyone with access to the network could try the default password to maliciously set DNS records.

6) Adding DNS records

Once the network is up and running, you can domain name records to the server by going to the base address (ie. 192.168.0.0) in a browser and entering the admin password set in the config. Then navigate to the DNS page, and click the Add Record button. The fields are:

• Name: Record hostname, ie. xyz.com
• Host: IP address of computer hostname should be directed to
• Port: Port filter for DNS record, defaults to any port if left empty (Advisory only)

Records can be edited by creating a new record with the same hostname.

Tip

DNS records will automatically be created on non-global networks if computers report a hostname when getting their IP address. The domain will be the hostname with a .lan appended.

Advanced

IP Addresses

IP address under IPV4 (the scheme that PeterOS uses) are made up of 4 octets (groups of 8 bits, or 2 hex digits) witch represent both the host and subnet address of the computer. IP addresses are often written as 4 numbers speared by periods such as 192.168.0.0, however the same address can be written in hex as 0xc0a80000, or 3232235520 in combined decimal.

For technical reasons, many aspects of the networking packages store IP addresses as combined decimal numbers. However, there are functions in the package to easily interchange between formats: net.ipFormat(ip) turns a numeric IP address into an IPV4 address string, and net.ipToNumber(ip) turns an IPV4 string to a numeric address.

Address spaces

Every network has an address space, often written as x.x.x.x/y, where x.x.x.x is the base address, and y indicates the number of bits in the host portion of the IP address.

For example 192.168.0.0/16 indicates that the base address is 192.168.0.0 with a subnet mask of 255.255.0.0. This means that the last 2 octets of the IP address are used for assigning addresses in the address space (192.168.0.0 - 192.168.255.255), although the highest address is reserved for broadcast (also address -1 for PeterOS)

Some address spaces are reserved for specific purposes, see the Reserved IP Addresses IPV4 table for specifics.

Network Address Transversal (NAT)

Network Address Transversal allows messages to pass between different networks. It works by passing messages out and assigning a connection ID to outgoing messages and changing the origin address to the external address of the NAT. Then, when a reply comes back, the NAT can change the destination address based on the connection ID linking it to the original sender.

Because of this, messages can only come back in as reply to an outgoing message. In order to have message come in without having to be a response, you need a forwarding rule

Forwarding rules

NAT forwarding rules give an internal destination for messages matching a filter.

The default NAT has 2 filters for forwarding rules: domain and port.

• Domain will only forward any message that indicates it is destined for the specified domain name. (use * for any domain)
• Port will only forward messages on the specified port. (use * for any port)

For example:

Forward all RTTP messages for xyz.com to 192.168.2.27 with a rule looking something like:

{"domain":"xyz.com", "port":10080, "dest":"192.168.2.27"}

Forward all messages for xyz.com to server.lan with a rule looking something like:

{"domain":"xyz.com", "port":"*", "hostname":"server.lan"}

Forward all messages on port 10021 to server.lan with a rule looking something like:

{"domain":"*", "port":10021, "hostname":"server.lan"}

Certificates & CAs

v1.8

Certificates allow clients to verify the authenticity of servers. Certificates are issued by a Certificate Authority (CA), witch in turn may have been issued by another CA, or the Central Certificate Authority (CCA). While everyone can issue derivate certificates, the CCA may issue an general CA certificate than can issue certificates with arbitrary ID. By this method, certificates for servers can be verified by a chain of certificates leading back to the CCA. For servers with a domain, the Certificate ID must match the domain, however, one server could have multiple certificates issued to it under different IDs.

Certificates include the public key of the server they were issued, the expiration time, and the issuer's ID. The certificate is then signed by the issuer's private key. If the certificate was issued by a intermediate certificate, it should also include (unsigned) the issuer's certificate and parent chain of certificates.

Derivative Certificates

All certificate holders can issue a derivative certificate who's ID ends with the issuer's ID, and that expires no later than the issuer's. For example: The holder of xyz.com can issue a derivate certificate with the ID abc.xyz.com.

Important

If derivative certificates are used, they should generally be sent with their parent chain to ensure that clients can verify them.

Verification

To verify a certificate, the client must know the public key of the issuer, with witch they can verify the signature on the certificate. In addition to the signature, the client checks if the certificate is expired, and that the issuer was allowed to issue it. Once it has been verified, the client may cache it.

Caution

Because the CCA's certificate is self signed (there is no one higher than them to sign it), it must be acquired from a trusted source, such as copying it from a computer that already has it.