NETSetup

Version: 0.1.0-proxmoxvms.808

Branch: feature/proxmoxvms

Tag: Autodeployed

Release Date: 04/21/2025 20:52:04

NEWS

Date: 2025-01-04

Currently not working is Proxmox on NVME Laptops.

Otherwise, running again so far.

Purpose

NETSetup allows users to automatically (or automagically) setup and configure any number of machines (servers, client computers, laptops) in a given organisation from OS installation, to server configuration, to domain joining of client computers, to software installation, all according to a given NETSetup configuration file.

In other words: NETSetup translates an enterprise structure to a network configuration and sets up the network accordingly.

In a future revision a new machine will receive its NETSetup automatically during its OOBE experience ("Just plug it in!"™).

Step by Step Process

@startuml

'Actors
actor Customer
actor Agent as "Agent (public)"
actor Ticketing as "Ticketing (public)"
actor Accounting as "Accounting (private)"
actor NETSetup as "NETSetup (private)"
actor Supplier as "Supplier (Alltron)"
actor Provider as "Provider (Dropbox)"
actor Computer
actor SWVendor as "Software Vendor (Microsoft)"
actor HWVendor as "Hardware Vendor (HP)"

'Contact
Customer -> Agent: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/050%20Kontaktaufnahme/Kontaktaufnahme%20V1.1.adoc callAgent() -> new order]]
Agent -> Ticketing: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/050%20Kontaktaufnahme/Ticketverwaltung%20in%20Freshdesk.adoc createNETSetupTicket(order) -> new ticket]]
Ticketing -> Customer: notifyCustomer(ticket)

'Delta
Agent -> Customer: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/100%20Offerte/Offertprozess.adoc#ist-soll-analyse requestCurrentMode(ticket)]] -> ensureConfig(ticket.customer.currentMode)[[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/Templates/TemplateCompany.adoc Template Company]] [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup.Tests/TestInfrastructure/OfflineCompany.cs Example Code]]
Customer -> Agent: responseCurrentMode(ticket) -> updateConfig(updatedCurrentMode)
Agent -> Customer: requestFutureMode(updatedCurrentMode.config)
Customer -> Agent: responseFutureMode(updatedCurrentMode.config) -> futureMode.config

'Quote
Agent -> Accounting: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/100%20Offerte/Offertprozess.adoc#offerterstellung createQuote(updatedCurrentMode.config, futureMode.config) -> new quote]]
Accounting -> Agent: returnQuote(quote)
Agent -> Customer: sendQuote(quote)
Customer -> Agent: responseQuote(quote)

'Config
Agent -> Supplier: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/230%20Beschaffung/Beschaffung.adoc createOrder(quote) -> new order]]
Supplier -> Agent: return order.Success
Agent -> NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup.Tests/Customers/TranslateCompanyToConfig.cs createConfigs(ticket, futureMode.config)]] -> new config[]
note over Agent, NETSetup: someConfig[] = { {HASTAG}ticket.json, ... }
NETSetup -> Provider: [[https://www.dropbox.com/home/NETSetup/BOOT/Config save config() ]]
Provider -> NETSetup: return save.Success
NETSetup -> Agent: return save.Success

'Prerequisite Steps
Supplier -> Agent: return order.HardwareHashes
Agent -> NETSetup: TODO: updateConfigs(ticket, hardwareHashes)
NETSetup -> Provider: TODO: updateConfigs(ticket, hardwareHashes)
Provider -> NETSetup: return update.Success
NETSetup -> Agent: return update.Success
Supplier -> Customer: [[https://github.com/osisa/NETSetup/blob/develop/docs/NETSetup/300%20Auslieferung/Auslieferung.adoc deliverOrder(setup)]]
Agent -> NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/input/NETSetupInstallUSB.adoc#NS-INSTALL-USB-CREATE-STICK Create NETSetup USB Stick]]
NETSetup -> Agent: NETSetup ready USB Stick

'Installation
loop For every computer
    Agent -> Computer: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/input/NETSetupInstall.adoc#NS-INSTALL-USB-USE-STICK plugIn(Power, USB Stick, Display, Keyboard)]]
    Agent -> Computer: turnOn()
    Agent -> Computer: hold(F9 or other key to get into Boot Menu)
    Agent -> Computer: select(USB Stick)
    Computer -> Computer: tries to boot USB Stick
    alt Can boot NTFS Partition
        Computer -> Computer: Boots WinPE from NTFS Partition
    else Lacks NTFS Driver
        Computer -> Computer: Boots FAT32 NTFS Driver
        Computer -> Computer: Boots WinPE from NTFS Partition
    end
    Computer -> Computer: WinPE runs startnet.cmd
    Computer -> Computer: startnet.cmd searches every drive for autoexecute.ps1
    Computer -> Computer: cd to drive and run autoexecute.ps1
    Computer -> NETSetup: autoexecute.ps1 runs [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/CLI/Commands/InstallCommand.cs NETSetup.exe install]]
    NETSetup -> Computer: logs NETSetup Version
    NETSetup -> Computer: os = GetOperatingSystem()
    NETSetup -> Computer: config = GetConfig()
    opt GetConfig()
        NETSetup -> Computer: register jsonSerializerOptions
        NETSetup -> Computer: isVirtualMachine?
        NETSetup -> Computer: isWinPE?
        NETSetup -> Computer: disks = GetAllDisksExceptUSB()
        NETSetup -> Computer: serialNumber = GetSerialNumber()
        NETSetup -> Computer: online = CheckOnline(timeout 10s)
        alt online
            NETSetup -> Computer: check for online map file
            note over Agent, NETSetup: foreach machine in config a map file. Nomenclature: SerialNumber#Ticket.json
            NETSetup -> Computer: download map file
            NETSetup -> Computer: check for single matching map file
        else
            NETSetup -> Computer: check for single matching map file
            NETSetup -> Computer: if no disks or not online -> try to install drivers
            NETSetup -> Computer: if is WinPE VM create temp partition
            NETSetup -> Computer: if no map file -> same check with online as before to get the config
            NETSetup -> Computer: if nothing is found, but there are configs locally -> UI select which
        end
    end
    alt os is WinPE
        NETSetup -> Computer: isOnline = CheckOnline
        NETSetup -> Computer: computer = GetComputer(config)
        NETSetup -> Computer: if no disk or not online -> try to install drivers
        NETSetup -> Computer: EnsureImage() - local check else download
        NETSetup -> Computer: installationDisk = GetDisk() - might require UI select disk
        alt operatingSystem.Contains(Windows)
            NETSetup -> Computer: CopyNETSetupFolderToImage(operatingSystem)
            NETSetup -> Computer: CurrentDirectory = Images\\operatingSystem
            NETSetup -> Computer: unattended = unattended.Replace(DISKID, targetDrive.Index)
            NETSetup -> Computer: StartProcess(setup.exe /unattend)
            NETSetup -> Computer: Reboot()
            Computer -> Computer: Boots Windows Setup from installationDisk
            Computer -> Computer: Windows auto setup via unattend.xml
            Computer -> Computer: Add scheduled Task to run NETSetup
            Computer -> Computer: Reboot()
            Computer -> Computer: Boots Windows from installationDisk
            Computer -> NETSetup: Run NETSetup
            NETSetup -> Computer: DomainJoin(currentConfig.Domain), ...
        else
            NETSetup -> Computer: installationDisk.CreateLinuxPartitions()
            NETSetup -> Computer: installationDisk.CopyEverythingToNewPartitions()
            NETSetup -> Computer: BIOS.DeactivateSecureBoot() #TODO
            NETSetup -> Computer: BIOS.DeactivateFastBoot() #TODO
            NETSetup -> Computer: BIOS.BootDriveFirst(targetDrive) #TODO
            NETSetup -> Computer: Reboot()
            Computer -> Computer: Boots GRUB Boot Manager
            Computer -> Computer: Boots Void Linux
            Computer -> Computer: Run /etc/profile
            Computer -> NETSetup: Run /efi/netsetup/autoexecute.sh
            NETSetup -> Computer: Partition Drive
            NETSetup -> Computer: Format Drive
            NETSetup -> Computer: Unpack Linux Image.tar.gz
            NETSetup -> Computer: Mount Image
            NETSetup -> Computer: Update BootEntry
            NETSetup -> Computer: Umount Image
            NETSetup -> Computer: Reboot()
        end
    end
end

'Approval and Billing
Agent -> Customer: [[https://github.com/osisa/NETSetup/tree/develop/docs/NETSetup/400%20Abnahme config.CreateApprovalForm())]]
Customer -> Agent: fillOut(config.approvalForm)
Agent -> Accounting: [[https://github.com/osisa/NETSetup/blob/develop/docs/Infobl%C3%A4tter/Software/Sage/Sage%20Start/Softwareinfoblatt%20Sage%20Start.adoc commissionBill(config)]]
Accounting -> Agent: returnBill(config.bill)
Agent -> Customer: sendBill(config.bill)
Customer -> Accounting: payBill(config.bill)
Accounting -> Agent: notify(config.bill.paid)
Agent -> Ticketing: closeTicket()

@enduml

NETSetup: Install using USB Stick

0. Requirements for Installation using NETSetup USB Stick

Read the entire Installation Instructions once from start to end before doing anything.

Target machine’s serial number has to be associated to a specific configuration. To do this goto the NETSetup.Tests Project and copy a customer file (e.g. Schnell.cs and at the bottom fill in all the details.The tests are supposed to be run in order to ensure the functionality of the configuration.One (by default ignored) test will upload the config files to the remote source, e.g. Dropbox).The most important methods are the ServerIP Range and the CreateCompany! (ALTERNATIVE to 1. for single Computers) Take #123.json from Dropbox and set the SerialNumber inside the desired type of Computer and ensure the {SerialNumber}#123.map File both exist.Copy them after creating the USB Stick in the NETSetup/Config Folder.

  1. Config has to be online of customer

  2. Physical access to the machine, which has internet cable, power, display and a keyboard connected.

  3. Press power button and hold the button labeled ESC until you see a menu

  4. Choose BIOS Setup / Computer Setup with arrow keys and press Enter

  5. Go through all Settings using the keys while looking for and setting the following settings (if you dont find the name, skip). In the end goto File > Save Changes and Exit and confirm yes and shutdown Machine with power button after reboot:

    • Secure Boot Configuration > Legacy Support / CSM / MBR Boot Disabled

    • USB / Removable Media Boot enabled

    • Secure Boot Configuration > Fast Boot Disabled

    • For Liberator VTx (Virtualization) Enabled

    • For Liberator Secure Boot Configuration > Secure Boot Disabled

    • For Liberator Boot Order > Push all entries with "USB" to the bottom

  6. A USB Stick of at least 16 GB (This USB Stick will be formatted and all data on it will be lost).

  7. Goto your existing Personal Computer and login with an Administrator

  8. Precondition: Chocolatey

  9. Press Win and X and open Terminal (Administrator) and confirm

  10. write the following into the box and press Enter:

choco install rufus -y

  1. Download this file from the documentation and (optionally) verify the correctness by: pressing right click on the file and copy path, type the following in the box "Get-FileHash" press space and right click and enter. If the the text is the same its correct.

BDEFCFF1234657B8975313592C03439787B3432E707D53902E7F2AA57DCAAAD7

1. Making the USB Stick

  1. Plug in your USB Stick to your computer

  2. Press Win and R and type "rufus" and press enter and confirm

  3. Select your USB Stick from the list at the top "Laufwerk" (Drive):

Select drive

  1. Click the "AUSWAHL" (SELECT) button and select the "NETSetup.iso" file from your Downloads folder.

Select image

  1. Make sure that the following Items are set as expected:

    • "Partitionsschema" is set to "GPT"

    • "Zielsystem" is set to "UEFI (ohne CSM)"

    • "Dateisystem" is set to "NTFS"

Proper settings

  1. Click the "START" button.

Start button

  1. Rufus might show you a warning. Click "OK" to confirm that all existing data on the stick will be deleted.

Warning

  1. Wait for the green progress bar at the bottom of the program to fill. This is a good time to get a cup of coffee.

Progress

  1. Rufus will show the text "FERTIG" (FINISHED) in the filled progress bar once it is done. You can unplug and use the NETSetup USB Stick now, and you can close rufus.

Done

2. Using the Install USB Stick

  1. Plug the USB Stick in the target machine on the back side (directly into the motherboard and not a front header USB).

  2. Power on the machine and hold down the F9 key (or a different one depending on your machine to enter the boot menu, refer to your manufacturers manual) until you enter the boot menu.

  3. Use the arrow keys to select USB. If you have multiple USB shows up, pick the topmost occurence and press enter

  4. If it asks you to select something, type the answer using the keyboard and press enter.

  5. Wait for the installation to finish, it reboots several times

For Liberator (or other linux based system) enter the Boot Menu 2 times and boot the disk and not the USB Stick

Note: If you’re setting up a new Windows Server Domain/AD, wait for the server to finish all its tasks before installing the clients. ~30min should be enough for reasonably up-to-date hardware. Connect the new machines to the LAN and boot them the same way with the USB Stick from before or a different one that has been made the same way

Workaround for Liberator Use this to setup machines on Liberator

3. USB Stick Troubleshooting

  • I cant boot the USB Stick. Check that UEFI Boot is enabled and NOT CSM/MBR BOOT!!!

  • I get an error while creating the USB stick:

    => Ensure that the USB stick is working and that it has enough space.

  • I cannot enter the boot menu:

    => <<BIOS-SETTINGS,Disable "Fast Boot">> in the BIOS. Consult Google if you are unsure on how to do this.

  • The NETSetup fails unexpectedly:

    => Ensure that you have the correct version of NETSetup.iso file (check the SHA-256 hash).
    => Make sure you follow the directions in <<Using the USB Stick>> correctly and ensure that the target machine's serial number is correctly registered in the config.

  • Windows Server installation fails:

    => Windows Server installation REQUIRES to be connected to an ethernet environment (a router is enough, it doesn't have to be a complete internet-activated environment with multiple machines). If there is no response on the ethernet port while installing, Windows Server will not install and setup ethernet and it will fail.

OLD / Legacy Installation Documentation

Executable (Advanced Functions)

NETSetup.exe

SHA-256 Hash of NETSetup.exe:
643C09B54FA98A50F8B366A6DE1461D89164A288ADFEE25FF0E68551A091FA3F

Usage

NETSetup.exe can install and configure aspects of a given machine. During a regular NETSetup installation it need not be downloaded seperately. The executable is provided here for advanced users.

Use "NETSetup.exe [command]" with one of the following commands:

  • ensure-file --file <filename> --dir <directory>:
    Ensures that the file <filename> exists in the directory <directory>. If it does not yet exist, it will be downloaded from dropbox. Root for the --file parameter is Dropbox:\NETSetup\boot

  • ensure-folder --folder <foldername> --dir <directory>:
    Ensures that the folder <foldername> with all its contents exists in the directory <directory>. If it does not yet exist, it will be downloaded from dropbox. Root for the --folder parameter is Dropbox:\NETSetup\boot

  • install Requires <driveroot>\NETSetup\config\config.json to be present, where <driveroot> is the current drive’s drive letter. Looks in <driveroot>\NETSetup\config\config.json for a configuration matching the machine’s serial number and uses it to update the machine to match the machine’s configuration (OS, software, domain, etc.).

  • set-ip --ip <ipaddress> --netmask <netmask> --gateway <geteway> --dns <dns>:
    Sets the machine’s ip address to <ip-address> and changes netmask, gateway and dns to the entries provided.

  • join-domain --domain <domain> --user <username> --password <password>:
    Tries to join the machine to the domain <domain> with the user <username> and its password <password>. The user must include the NETBios-domain (e.g. osisa\user.name)

  • get-id: Gets the machin’s BIOS serial number (SMBIOS).

  • get-md5 --file <filename>:
    Gets the md5 hash of the file <filename>.

  • get-sha --file <filename>:
    Gets the sha256 hash of the file <filename>.

  • get-crc --file <filename>:
    Gets the crc-32 hash of the file <filename>.

  • check-sha --file <filename> --sha <checksum>:
    Checks that the sha256 checksum of the file <filename> matches the provides <checksum>

  • reboot-oobe [--force [1|true]]: Reboots the machine to the OOBE environment after confirmation. Optionally use "--force 1" to skip confirmation. WARNING: Once the machine is in OOBE environment, the entire process must be finished before you can return to the regular desktop.

  • rename --name <name> [--force [1|true]]:
    Renames the machine to <name>. Asks for confirmation unless "--force 1" is specified. WARNING: Using this while joined to a domain will mess up your system because the AD entry of your machine is not updated to match the new name. Leaving the domain will then be impossible because (presumably) no computer with the new name <name> exists in the domain.

  • wlan --ssid <ssid> --password <password>:
    Tries to connect your wifi to the ntwork with the SSID <ssid> using the password <password>.

Examples:

.\NETSetup.exe set-ip --ip 192.168.1.123 --netmask 255.255.255.0 --gateway 192.168.1.1 --dns 8.8.8.8
.\NETSetup.exe get-sha c:\temp\document.docx
.\NETSetup.exe wlan --ssid swisscom --password abcd-1234-efgh-5678-ijkl
.\NETSetup.exe install

Developer Info

When you push changes to the NETSetup repository, the corresponding Git Action tests, builds, and updates the executable and the ISO-Image automatically.

The entrypoint for the executable is CLI/NETSetup.cs/Main(). There it adds all the commands to the application.

The Install command is in CLI/Commands/InstallCommand.cs

You can create an offline ISO with "__main__.cs > [TestMethod] CreateOffline"

If Offline Install ensure Image, Drivers and Config are copied onto USB Stick. If singular computer ensure the Config and MapFile as described in Requirements

Linux Notes

how to extract tar.gz

gunzip -t proxmox.tar.gz

how to extract squashed image to valid image

unsquashfs -x -f squashfs.img LiveOS/ext3fs.img -d void

delte previous file to ensure no error there

sudo rm squashfs.img

if not yet make new folder /mnt

mkdir /mnt

mount image locally to mnt/void

sudo mount -o loop squashfs-root/LiveOS/ext3fs.img /mnt/void

modify files on the image, eg:

sudo nvim /mnt/void/etc/profile

or even enter the image as if you booted it with

sudo chroot /mnt/void

unmount when done

sudo umount /mnt/void

and then repack the image

sudo mksquashfs squashfs-root squashfs.img

only good way to style bash shell / terminal btw

export PS1="[ \[\e[31m\]\u\[\e[m\]@\[\e[36m\]\H\[\e[m\]: \[\e[33m\]\w\[\e[m\] ] \[\e[36m\]\t\[\e[m\] \[\e[31m\]\\$\[\e[m\] "