The Configuration File

All user configuration (except server-side command line flags) is in the configuration file. That configuration file follows the TOML specification.

This is an example configuration file for a constellation with one shell of 1,584 satellites and one ground station:

# The bounding box of the area you would like to simulate. Satellite servers
# outside of this bounding box are suspended to save on resources. Provide
# coordinates in a Lat-Long (bottom left) Lat-Long (top right) format. You may
# want to check out http://bboxfinder.com/ to find your bounding box.
bbox = [34.657635, -13.881488, 58.794799, 26.196637]

# Set the minimum update resolution in seconds. For example, a value of 1 means
# that satellite positions are updated every second. Lower intervals lead to
# more resource consumption, higher intervals are less accurate.
resolution = 1

# Set the duration of the simulation in seconds. This is the time that satgen.py
# will run for.
duration = 300

# Set the offset for the simulation in seconds. This is the time that satgen.py
# will start at. This is optional and defaults to 0. It is not necessary to set
# this for symmetrical constellations, but can be quite useful if you only want
# to have a single plane of satellites but need them to go over a specific point
# on Earth. Note that the ascending node of the first plane is always at Long=0.
# If you want it to be at Long=X, you need to set the offset to X * 86400 / 360.
offset = 0

# The network_params section lets you specify parameters for networking between
# your machines. These can also be overridden for different shells or ground
# stations.
[network_params]
# Bandwidth sets the available bandwidth for each ISL in Kbit/s. Current
# estimates set this at 10Gbit/s.
bandwidth_kbits = 10_000_000

# Whether a satellite is available from a ground stations depends on the
# minimum elevation in degrees (0 <= min_elevation <= 90). If there is no
# satellite within this distance from a ground station, that ground station is
# cut off from the satellite network.
min_elevation = 40

# There are different options for connecting a ground station. The main
# question is whether a ground station can connect to all available satellites
# simultaneously ("all" option), or one nearest satellite for each shell ("one"
# option).
ground_station_connection_type = "all"

# The compute_params section lets you configure Firecracker machine
# configuration options for your servers. The values you set here are
# considered the defaults but can be overridden for individual shells or
# ground stations.
[compute_params]
# Set the number of vCPUs that you want to allocate to each active server.
vcpu_count = 1
# Set the memory allocation for each server in MiB.
mem_size_mib = 128
# Set the maximum disk size for your machine. An empty sparse file will be
# created with a MAXIMUM size of disk_size_mib, and that file expands as your
# machine writes into it. Depending on the storage available on your hosts, you
# may run into problems.
disk_size_mib = 20_000

# In addition to the default kernel boot parameters, you can also specify your
# own. These will be passed to the machine at boot time. Be sure not to have
# duplicate parameters with the defaults (these cannot be changed without
# recompiling Celestial):
#
#   console=ttyS0
#   noapic
#   reboot=k
#   panic=1
#   pci=off
#   tsc=reliable
#   quiet
#   ipv6.disable=1
#   nomodules
#   overlay_root=vdb
#
# Additionally, Firecracker passes these parameters:
#
#   ip (IP configuration)
#   root (root device configuration)
#   virtio_mmio.device
#
# You can also pass the empty list if you do not require this parameter.
boot_parameters = ["8250.nr_uarts=0"]
# Specify the compiled kernel to use for your microVMs. The filename you
# specify here must be available in the "/celestial" folder on your servers.
kernel = "test.bin"
# Specify the root filesystem image to use for your microVMs. The filename you
# specify here must be available in the "/celestial" folder on your servers.
rootfs = "rootfs.img"

# You can define an arbitrary number of shells with the [[shell]] keyword. For
# sake of brevitiy, we only define a single shell here. Note that you can leave
# out some settings that override previously defined defaults.
[[shell]]
# One basic parameter for a shell is the amount of planes it has. Each plane is
# one orbital plane.
planes = 72
# Then, define how many satellites you would like for each plane of the shell.
# Satellites are evenly spaced around each orbit.
sats = 22
# Define the altitude of the shell in kilometers. This is used to compute the
# semi-major axis as altitude + earth_radius.
altitude_km = 550
# Angle of the satellite orbit plane measured from the Earth's equatorial
# plane, in degrees.
inclination = 53.0
# The angle of arc (in degrees) that the ascending nodes of all the orbital
# planes is evenly spaced along. For example, seting this to 180 results in a
# Pi constellation like Iridium. For a standard 2Pi constellation like
# Starlink, set this to 360.0.
arc_of_ascending_nodes = 360.0
# The eccentricity of the orbit defines its "oval-ness". The value is between
# 0.0 (perfectly circular orbit) and 1.0 (completely parabolic). For LEO
# constellations, this should be 0.0. For reference, STARLINK-2046 and
# ONEWEB-145 have this as 0.0001205 and 0.0012512, respectively, at the time of
# writing.
eccentricity = 0.0

# You can also override compute_params for specific shells. For example, you
# might desire to allocate more memory to the servers in a specific shell.
[shell.compute_params]
mem_size_mib = 256

# Finally, you can also set network_params for specific shells. For example,
# you may want to set higher bandwidths for a specific shell.
[shell.network_params]
bandwidth_kbits = 10_000_000

# In addition to satellites, ground stations are another important part of your
# constellation. Each ground station is a server on earth that communicates
# with the satellite constellation over radio links. You can specify up to
# 16,384 ground station with the [[groundstation]] tag, or no ground stations
# at all.
# Ground stations servers are always active, regardless of whether they lie in
# the bounding box or not.
[[ground_station]]
# You can set a name for the ground station. This will be available to the
# microVM over the included HTTP information service.
name = "Berlin"
# Set a latitude and longitude for the ground station. This location is used to
# calculate nearby satellites and establish links to the satellite
# constellation.
lat = 52.51492067
long = 13.32666938

# By default, ground stations inherit the compute_params parameters defined
# before, but those can of course be overridden. Generally, you may want to
# allocate more resources at ground stations.
[ground_station.compute_params]
vcpu_count = 4
mem_size_mib = 8192
disk_size_mib = 5_000

# Additionally, you can also set network_params specifically for a ground
# station if you want to override the standard values set above.
[ground_station.network_params]
bandwidth_kbits = 1_000_000