reference.conf

drasyl {
  # The network ID is an integer number which isolates drasyl networks. Connections between nodes
  # will occur only if both peers use the same network ID. The main network has ID 1. If you supply
  # your own custom network ID which is different than the main network, your nodes will not connect
  # to other nodes and form a private network. If you’re planning to create your own network on the
  # Internet, it’s best to choose a network ID that isn’t already used.
  # Note: Make sure that the configured Super Peers use the same network ID.
  network.id = 1

  # Each node has a unique identity. It is composed of a public-private key pair. The public key
  # is used as the node's address.
  identity {
    # This proof of work can be can be provided as evidence that work has been put into
    # the creation of the identity.
    proof-of-work = null

    # This private key must be kept secret. Otherwise, other nodes may use this node's identity
    # to sign and decrypt messages.
    secret-key = ""

    # Path to the file with the identity. Is only read if public-key and private-key are
    # empty. If the file does not exist, a new key pair is generated and stored in the file.
    path = "drasyl.identity"
  }

  message {
    # Number of outgoing messages that can be buffered before they get processed.
    # The buffer acts as a backpressure mechanism to prevent an application from adding messages to
    # the overlay middle faster than they can be processed. An overflow can lead to out of memory
    # states or a high cpu utilization.
    # A value of `0` means that the buffer has no capacity limit.
    buffer-size = 0
  }

  # The drasyl node can use UDP to discover and communicate with other peers.
  remote {
    # If you disable UDP, no interaction with non-local nodes is possible!
    enabled = true

    # IP address that the server should listen on.
    bind-host = "0.0.0.0"

    # The port that the server should listen on.
    #
    # A value of `0` means that a random port number is automatically selected on every start.
    #
    # The value `-1` means that a port in the range 22528 and 65528 is derived from the public key.
    # This is necessary because some NAT devices behave unexpectedly when multiple nodes in the
    # local network use the same local port (via UPnP).
    bind-port = -1

    # If this option is enabled, drasyl tries to automatically create a port mapping on discovered
    # UPnP-IGD/NAT-PMP/PCP devices. Disabling this option makes the automatic discovery of this node
    # more difficult. If you create a super-peer node, it is recommended to disable this ption and
    # open a static port by yourself. If you are on a public or corporate network, this feature will
    # probably not work (is denied). In this case, we recommend disabling this function.
    #
    # Note for Windows User:
    # Some Windows machines that prevent outbound SSDP broadcasts (M-SEARCH) from
    # being transmitted on the wire, which in turn prevents us from ever seeing a unicasted response
    # from the device. The issue appears to be caused by Microsoft's "SSDP Discovery" service -
    # when that service is enabled it cycles which interface our INADDR_ANY UDP multicasts go out
    # over, even on systems with only a single physical interface (for example, virtual network
    # interfaces created by VMware on the Host OS). See also:
    # http://stackoverflow.com/questions/32682969/windows-ssdp-discovery-service-throttling-outgoing-ssdp-broadcasts
    #
    # A workaround is to change the drasyl.remote.bind-host value to a specific interface (not 0.0.0.0)
    expose.enabled = true

    # The individual nodes send each other ping messages for the discovery and maintaining of NAT
    # holes.
    ping {
      # Determine how often this node will send ping messages to peers. Too long intervals can lead
      # to unrealiable connections. Therefore we recommend not to change this value. Must be a
      # positive value.
      interval = 5s

      # Specify the maximum time the node should wait for a response to ping messages before the
      # peer is considered unreachable and removed from the neighborhood list. Must be a positive
      # value.
      timeout = 30s

      # Defines how long the node sends ping messages to other peers without application
      # communication. Must be a positive value.
      communication-timeout = 60s

      # Defines the maximum number of peers to be sent ping messages simultaneously. Set to 0 to
      # allow unlimited number of connections.
      max-peers = 100
    }

    # Defines how often this node should try to support the sending and receiving peers to establish
    # a direct connection by using NAT hole punching when relaying messages.
    # An interval of 0 deactivates the support.
    unite.min-interval = 20s

    # The node can register itself to so-called super peers, which acts as a registry for nodes on
    # the network, a default gateway for messages, and will support with NAT hole punching.
    super-peer {
      # When enabled, the node attempts to register itself to super peers via the endpoints listed
      # below. This node cannot act as a super peer for other nodes as long as this option is
      # enabled.
      enabled = true

      # Endpoints that are used to connect to super peers.
      # Note: Make sure that the configured super peers uses the same network ID as this node.
      endpoints = [
        "udp://sp-rjl1.drasyl.org:22527?publicKey=5b4578909bf0ad3565bb5faf843a9f68b325dd87451f6cb747e49d82f6ce5f4c&networkId=1",
        "udp://sp-fkb1.drasyl.org:22527?publicKey=c0900bcfabc493d062ecd293265f571edb70b85313ba4cdda96c9f77163ba62d&networkId=1",
        "udp://sp-nyc1.drasyl.org:22527?publicKey=bf3572dba7ebb6c5ccd037f3a978707b5d7c5a9b9b01b56b4b9bf059af56a4e0&networkId=1",
        "udp://sp-sgp1.drasyl.org:22527?publicKey=ab7a1654d463f9986530bed00569cc895697827b802153b8ef1598579713045f&networkId=1",
      ]
    }

    # Static routes to other peers can be specified here (peer's public key -> host:port).
    # This allows direct remote communication with other peers without the need for a discovery or
    # presence of a super peer.
    # Note: Make sure that the peer is permanently available at given address. drasyl will send all
    # messages to this address without any availability checks.
    static-routes {
      # example:
      # 033e8af97c541a5479e11b2860f9053e12df85f402cee33ebe0b55aa068a936a4b = "140.211.24.157:22527"
    }

    # drasyl can use the file system to discover other drasyl nodes running on the local computer.
    local-host-discovery {
      # When enabled, the node writes its own information to the directory specified below. At the
      # same time, the directory is also searched for information off other nodes.
      enabled = true

      # This directory is searched for other drasyl nodes. If nothing is specified here, a
      # "drasyl-discovery" directory in the system's temp directory will be used.
      path = ""

      # Defines how long the information written to the directory should be considered as up-to-date.
      # Older files in the directory are considered outdated and therefore will be ignored.
      # This node automatically refreshes its own information to keep them up-to-date.
      # All nodes of a directory should use the same lease time. Must be a positive value.
      lease-time = 1m

      # If enabled, the file system is requested to notify about updated files in the directory
      # defined above. As some file systems notify unrealiably or with a too long delay, this
      # push-based mechanism can be disabled. In this case a pull-based notification method will be
      # used.
      watch.enabled = true
    }

    # drasyl can discover oder nodes running within the same network via ip multicast without
    # relying on a super peer. This is realized via the group 239.22.5.27. For this, a second UDP
    # server is started on port 22527 to receive these multicast messages addresses to this group.
    # All nodes within a single JVM will share this server. If more than one JVM with nodes is
    # started, only the first JVM will be able to start a multicast server. Nodes in other JVMs will
    # not able to discovery nodes via IP multicast on the local network. This can be avoided by
    # binding each JVM's UDP server on another network interface (see below).
    #
    # The used multicast group address can be changed by setting java system property
    # org.drasyl.remote.multicast.address (default value: 239.22.5.27:22527).
    #
    # The used network interface for ip multicast can be changed by setting java system property
    # org.drasyl.remote.multicast.interface (if nothing is specified, the default interface is used)
    #
    # The UDP multicast bind address can be changed by setting java system property
    # org.drasyl.remote.multicast.bind-host (default value: 0.0.0.0)
    #
    # Note: Currently, nodes running on some windows-based systems cannot be discovered via ip
    # multicast. We are working on a fix. For more information please visit:
    # https://github.com/drasyl/drasyl/issues/204.
    local-network-discovery {
      # When disabled, no ip multicast and no additional udp server will be used.
      enabled = true
    }

    # Sets the timeout to do a handshake between two nodes in a TCP-like manner
    handshake.timeout = 10s

    message {
      # Limits the lifespan of a message and prevents it from circulating indefinitely on the
      # network. Every outbound message starts with the value defined here. Each node decreases the
      # message's hop-limit value before routing it to the next node. If the hop-limit value reaches
      # zero before the message arrives at its destination, then the message is discarded. Must be a
      # positive value. Must not be greater than 127.
      hop-limit = 8

      arm {
        # Encrypts the protocol-specific messages required to participate in the overlay
        protocol {
          # If activated, outbound messages are armed (encrypted) and inbound messages are
          # disarmed (decrypted). Disable this option for only testing!!! Otherwise, the
          # integrity, authenticity, and confidentiality of messages are not given.
          # All nodes in the network must use the same setting, otherwise, no communication is possible.
          enabled = true

          session {
            # The maximum number of sessions/connections that a node may hold in memory simultaneously
            # to other nodes. This values limits the total amount of secure connections a node can
            # establish!
            # Super peers usually require more sessions than normal nodes.
            max-count = 100000

            # Time after which a non used session expires and will be dropped to save memory.
            # Too high values can increase memory usage.
            expire-after = 5m
          }
        }

        # Encrypts the application-specific messages required to participate in the app-context
        application {
          # If activated, outbound messages are armed (encrypted) and inbound messages are
          # disarmed (decrypted). Disable this option for only testing!!! Otherwise, the
          # integrity, authenticity, and confidentiality of messages are not given.
          # All nodes of the same application must use the same setting, otherwise, no communication is possible.
          enabled = true

          agreement {
            # The maximum number of agreements allowed per peer.
            # The number should be at least 1 for PFS to be possible.
            # Too large numbers are not recommended.
            # This memory is only needed to be able to continue decrypting/encrypting messages with
            # an "old" agreement during a key exchange that is taking place.
            # To disable PFS choose 0 as value.
            max-count = 10

            # Time after which a PFS agreement expires and a new key exchange must take place.
            # Too high values can reduce security.
            expire-after = 30m

            # Time after which a new key exchange is retried if this could not be performed
            # successfully before. Values that are too small are inefficient.
            # Values that are too large reduce security.
            retry-interval = 10s
          }
        }
      }
    }

    # If no connection via UDP can be established with the super peers, the node can try to
    # establish a TCP-based connection to the super peers as a last resort. This is useful for very
    # restrictive networks which, for example, block all UDP traffic or only allow connections to
    # HTTP(S) ports.
    tcp-fallback {
      # Enable or disable the TCP fallback mechanism.
      enabled = true

      # Configures the TCP server. This is only started if the node is configured as super peer
      # (drasyl.remote.super-peer.enabled = false).
      server {
        # IP address that the tcp server should listen on.
        bind-host = "0.0.0.0"

        # The port that the server should listen on.
        # As the tcp fallback mechanism is mainly intended for very restrictive networks, an HTTP(S)
        # port should be used, as these are usually open.
        bind-port = 443
      }

      # Configures the TCP client. This is only started if the node is configured as client
      # (drasyl.remote.super-peer.enabled = true).
      client {
        # Time without response from the super peer before a connection is attempted via TCP. Must
        # be a positive value.
        timeout = 60s

        # Address (hostname and port) that is used to connect to a super peer via TCP.
        # Note: Make sure that the configured address points to one of the super peers defined in
        # `drasyl.remote.super-peer.endpoints`
        address = "sp-fkb1.drasyl.org:443"
      }
    }
  }

  # SNTP server for time checks. If empty uses the default gateway as NTP server
  sntp-server = []

  # drasyl can use shared memory to automatically discover and communicate with other nodes running
  # on the same JVM
  intra-vm-discovery.enabled = true

  # Upon communication with a peer, a virtual channel is created which handles outgoing and incoming
  # communication to that peer.
  channel {
    # Closes the channel if no write or read operation has taken place with the remote station. Must
    # be a positive value or set to 0 to have to disable automatic closing of inactive channels.
    # Keep in mind that too many open channels can lead to out of memory states.
    inactivity-timeout = 300s
  }

  # Every plugin that should be auto-loaded by drasyl, must be added to this object as object.
  # Only plugins that extends the AutoloadablePlugin class can be auto-loaded by drasyl.
  # The selected key for the object is also the path where all configurations are
  # provided to the plugin.
  # Example:
  # "org.drasyl.plugin.TestPlugin" {
  #  enabled = true
  # }
  plugins {}

  # The messages that drasyl nodes send to each other are JVM objects. Message passing between nodes
  # living on the same JVM is straightforward. It is done via reference passing. However, messages
  # that must leave the JVM to reach a node running on a different host must go through some form of
  # serialization (i.e., the objects must be converted to and from byte arrays).
  #
  # For drasyl to know which Serializer to use for what, you bind java classes to implementations of
  # the org.drasyl.serialization.Serializer you wish to use.
  #
  # By default, drasyl serializes only java primitives and strings. Additional classes must be
  # enabled manually. Please note the potential security implications below.
  #
  # A reckless implementation of a permitted class can leave the entire application and all
  # executing machines vulnerable to remote code execution.
  #
  # An attacker is in general interested in all "non-pure" methods, which have promising side
  # effects. A method is "pure" if:
  #   - The execution of the function has no side effects, and
  #   - the return value of the function depends only on the input parameters passed to the function.
  #
  # For example, a vulnerability could be a setter or getter that connects to a database.
  # A vulnerable class is for example the ch.qos.logback.core.db.DriverManagerConnectionSource.
  # An attacker can choose the URL arbitrarily. By calling getConnection,
  # Server Side Request Forgery (SSRF) and DOS attacks can occur.
  #
  # You can find more about this in the following literature:
  #   - Java Unmarshaller Security - Turning your data into code execution by Moritz Bechler:
  #     https://raw.githubusercontent.com/mbechler/marshalsec/master/marshalsec.pdf
  #   - Automated Discovery of Deserialization Gadget Chains by Ian Haken:
  #     https://i.blackhat.com/us-18/Thu-August-9/us-18-Haken-Automated-Discovery-of-Deserialization-Gadget-Chains-wp.pdf
  #   - Marshalling Pickles by Chris Frohoff and Garbriel Lawrence:
  #     https://frohoff.github.io/appseccali-marshalling-pickles/
  serialization {
    # This is where serializer implementations are registered. Each implementation must implement a
    # public default constructor.
    serializers {
      # java primitives
      primitive-boolean = "org.drasyl.node.handler.serialization.BooleanSerializer"
      primitive-byte = "org.drasyl.node.handler.serialization.ByteSerializer"
      primitive-char = "org.drasyl.node.handler.serialization.CharacterSerializer"
      primitive-float = "org.drasyl.node.handler.serialization.FloatSerializer"
      primitive-int = "org.drasyl.node.handler.serialization.IntegerSerializer"
      primitive-long = "org.drasyl.node.handler.serialization.LongSerializer"
      primitive-short = "org.drasyl.node.handler.serialization.ShortSerializer"

      # stock java
      bytes = "org.drasyl.node.handler.serialization.ByteArraySerializer"
      string = "org.drasyl.node.handler.serialization.StringSerializer"
      java = "org.drasyl.node.handler.serialization.JavaSerializer"

      # libraries
      jackson-json = "org.drasyl.node.handler.serialization.JacksonJsonSerializer"
      proto = "org.drasyl.node.handler.serialization.ProtobufSerializer"

      # example for own implementation
      # myown = "docs.serialization.MyOwnSerializer"
    }

    # Class to Serializer binding. You only need to specify the name of an interface or abstract
    # base class of the messages.
    bindings {
      # These bindings are used for incoming messages sent from other nodes
      inbound {
        "[B" = bytes
        "java.lang.String" = string
        "java.lang.Boolean" = primitive-boolean
        "java.lang.Byte" = primitive-byte
        "java.lang.Character" = primitive-char
        "java.lang.Float" = primitive-float
        "java.lang.Integer" = primitive-int
        "java.lang.Long" = primitive-long
        "java.lang.Short" = primitive-short

        # disabled by default for security reasons
        # "java.io.Serializable" = java

        # example for array serialization with java
        # "[Ljava.lang.String;" = java

        # example for serialization with Jackson
        # "docs.serialization.MyOwnSerializable" = jackson-json

        # example for serialization with Google Protocol Buffers
        # "com.google.protobuf.Message" = proto

        # example for serialization using own serializer
        # "docs.serialization.MyOwnSerializable" = myown
      }

      # These bindings are used for outbound messages sent to other nodes
      outbound {
        "[B" = bytes
        "java.lang.String" = string
        "java.lang.Boolean" = primitive-boolean
        "java.lang.Byte" = primitive-byte
        "java.lang.Character" = primitive-char
        "java.lang.Float" = primitive-float
        "java.lang.Integer" = primitive-int
        "java.lang.Long" = primitive-long
        "java.lang.Short" = primitive-short

        # disabled by default for security reasons
        # "java.io.Serializable" = java

        # example for array serialization with java
        # "[Ljava.lang.String;" = java

        # example for serialization with Jackson
        # "docs.serialization.MyOwnSerializable" = jackson-json

        # example for serialization with Google Protocol Buffers
        # "com.google.protobuf.Message" = proto

        # example for serialization using own serializer
        # "docs.serialization.MyOwnSerializable" = myown
      }
    }
  }
}