Skip to content

Latest commit

 

History

History
126 lines (107 loc) · 4.95 KB

README.adoc

File metadata and controls

126 lines (107 loc) · 4.95 KB
Raw

Boundary Node Guest OS

This contains the instructions to build the system images for a Boundary Node. More detailed information can be found here.

Build a Boundary Node image

To build a boundary node image, refer to the IC-OS README

Run a Boundary Node locally

Important: These are just minimal instructions to run a boundary node locally.

  • Build the BN image as described above using bazel build //ic-os/boundary-guestos/envs/dev

  • Build the virtual USB stick using build-bootstrap-config-image.sh.

    Note:

    • Make sure to specify an appropriate output path.

    • The ipv4/ipv6 arguments make sure that the firewall allows all external connections.

    • The elasticsearch_url cannot be empty.

    • The nns_public_key is required to point to a file. It suffices to create an empty file.

      ic-os/boundary-guestos/scripts/build-bootstrap-config-image.sh \
  OUTPUT_PATH/virtual-usb.img \
  "--hostname" "boundary-xyz" \
  "--ipv6_replica_ips" "::/0" \
  "--ipv4_http_ips" "0.0.0.0/0" \
  "--ipv6_http_ips" "::/0" \
  "--ipv6_debug_ips" "::/0" \
  "--ipv6_monitoring_ips" "::/0" \
  "--name_servers" "2606:4700:4700::1111 2606:4700:4700::1001" \
  "--elasticsearch_url" "https://nodomain.icp" \
  "--nns_public_key" "artifacts/tmp/nns_public_key.pem" \
  "--nns_url" "::"

  • Prepare an XML configuration file for virsh using the following template by replacing:

    • {{ BN_NAME }} with a unique name (e.g., test-bn-1)

    • {{ UUID }} with a unique ID (e.g., 7a2463af-1ef4-487d-ac26-85c8733e17ea). UUIDs can be generated here.

    • {{ PATH_TO_DISK_IMG }} with the path to the BN image (e.g., disk.img).

    • {{ PATH_TO_USB_IMG }} with the path to the virtual USB stick (e.g., virtual-usb.img).

      <domain type='kvm' id='1'>
  <name>{{ BN_NAME }}</name>
  <uuid>{{ UUID }}</uuid>
  <memory unit='KiB'>4194304</memory>
  <currentMemory unit='KiB'>4194304</currentMemory>
  <vcpu placement='static'>2</vcpu>
  <os>
    <type arch='x86_64' machine='pc-q35-5.0'>hvm</type>
    <loader readonly='yes' type='pflash'>/usr/share/OVMF/OVMF_CODE.fd</loader>
    <boot dev='hd'/>
  </os>
  <features>
    <acpi/>
    <apic/>
  </features>
  <devices>
    <emulator>/usr/bin/qemu-system-x86_64</emulator>
    <disk type='file' device='disk'>
      <driver name='qemu' type='raw'/>
      <source file='{{ PATH_TO_DISK_IMG }}' index='1'/>
      <backingStore/>
      <target dev='vda' bus='virtio'/>
      <alias name='virtio-disk0'/>
      <address type='pci' domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
    </disk>
    <disk type='file' device='disk'>
      <driver name='qemu' type='raw'/>
      <source file='{{ PATH_TO_USB_IMG }}'/>
      <target dev='hda' bus='usb' removable='on'/>
      <address type='usb' bus='0' port='1'/>
    </disk>
    <interface type='bridge'>
      <mac address='52:54:00:4f:f8:ec'/>
      <source bridge='br0'/>
      <target dev='vnet0'/>
      <model type='virtio'/>
      <alias name='net0'/>
      <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
    </interface>
    <interface type='bridge'>
      <mac address='52:54:00:33:4e:b0'/>
      <source bridge='vlan66'/>
      <target dev='vnet1'/>
      <model type='virtio'/>
      <alias name='net1'/>
      <address type='pci' domain='0x0000' bus='0x02' slot='0x00' function='0x0'/>
    </interface>
    <serial type='pty'>
      <source path='/dev/pts/44'/>
      <target type='isa-serial' port='0'>
        <model name='isa-serial'/>
      </target>
      <alias name='serial0'/>
    </serial>
  </devices>
</domain>

  • Run sudo virsh create PATH_TO_XML_CONFIG_FILE to start the Boundary Node virtual machine.

  • Run sudo virsh --connect qemu:///system console BN_NAME to connect to the console of the virtual machine. The username is root and the password is root.

  • To exit the virsh console use Ctrl + ]

  • Run sudo virsh destroy BN_NAME to destroy the VM when you are done.

Note: If you need to make changes, just destroy the VM, rebuild the images you need and create the VM again. The XML configuration file can be reused.

Developing with the system

The entirety of the actual Ubuntu operating system is contained in the rootfs/ subdirectory. See instructions there on how to make changes to the OS and the included components.

Directory organization

The directory rootfs/ contains everything related to building a bootable Ubuntu system. It uses various template directories (e.g., opt/) that are simply copied verbatim to the target system — you can just drop files there to include them into the image.

The directory ../bootloader/ contains everything related to building EFI firmware and the grub bootloader image.

All build steps are contained in the ../defs.bzl and the target specific directories (e.g., prod/BUILD.bazel).