ebpf-for-windows/docs/InstallEbpf.md

Installing eBPF into a Test VM

Follow the VM Installation Instructions for one-time setup of a test VM. Once the one-time setup has been completed, the following steps will install or update the eBPF installation in the VM.

Method 1 (Install a release with the MSI installer)

Do the following from within the VM:

1. Download and install the VC++ Redist package from this location.

2. Download the ebpf-for-windows.msi file from the latest release on GitHub.

3. Execute the ebpf-for-windows.msi file you downloaded.

4. After accepting the License and selecting the desired installation folder (default will be "C:\Program Files\ebpf-for-windows"), the following components will be selectable from the Installation Wizard:

   • Runtime Components (mandatory): this feature adds the eBPF runtime and core components, which are also required by the other components. If you select only this feature, only native code generation is enabled.
     • JIT (optional): this sub-feature adds support for JIT-compiled eBPF programs and (in a Debug build only) interpreted eBPF programs.
   • Development (optional): this feature adds headers and libraries used for development. If you only want to use eBPF for development rather than running programs, you can use the NuGet package instead of the MSI.
   • Testing (optional): this feature adds tests for the eBPF runtime for use by eBPF runtime developers.

An unattended install/uninstall is also supported, through the direct use of msiexec.exe.

Following is an example that shows a full-feature installation/uninstallation, using "C:\eBpfForWindows" as a custom installation folder:

• Installation:

  # Debug MSI (including the JIT component)
  C:\Windows\system32\msiexec.exe /i ebpf-for-windows.msi INSTALLFOLDER="C:\eBpfForWindows" ADDLOCAL=eBPF_Runtime_Components_JIT,eBPF_Development,eBPF_Testing /qn
  
  # Release MSI
  C:\Windows\system32\msiexec.exe /i ebpf-for-windows.msi INSTALLFOLDER="C:\eBpfForWindows" ADDLOCAL=eBPF_Development,eBPF_Testing /qn
  

  Note: like in the graphical Installation Wizard, you can also customize the installation by choosing what optional features should be installed (i.e., eBPF_Runtime_Components_JIT, eBPF_Development and eBPF_Testing), and assigning the comma-separated values to the ADDLOCAL parameter. The above commands, besides the mandatory Runtime_Components, also install the Development and Testing components.

• Uninstallation:

  C:\Windows\system32\msiexec.exe /x ebpf-for-windows.msi /qn
  

Troubleshooting logs from the Windows Installer can be obtained be appending the \lv <filename> option to the install command line (for verbose logs), e.g.:

C:\Windows\system32\msiexec.exe /i ebpf-for-windows.msi *<other options>* /lv c:\installer-logs.txt

Method 2 (Install files you built yourself)

This method uses a machine that has already built the binaries for x64/Debug or x64/Release.

1. Deploy the binaries to C:\Temp in your VM, as follows:

   • If you built the binaries from inside the VM, then from your ebpf-for-windows directory in the VM, run:

     .\x64\debug\deploy-ebpf -l
     

   • Otherwise, if you built the binaries on the host machine, then from your ebpf-for-windows directory on the host machine, start an admin Powershell on the host machine and run:

     .\x64\debug\deploy-ebpf --vm="<test-vm-name>"
     

     or, to also copy files needed to run various tests, run:

     .\x64\debug\deploy-ebpf --vm="<test-vm-name>" -t
     

     or, to copy files to a specific directory, including file shares, run:

     .\x64\debug\deploy-ebpf -l="c:\some\path"
     

2. From within the VM, install the binaries by starting an administrator Command Prompt shell (cmd.exe) , and running the following commands:

   cd C:\Temp
   
   powershell -ExecutionPolicy Bypass .\scripts\setup-ebpf.ps1
   

Method 3 (Install files you built yourself, with a VM checkpoint)

This method uses a machine that has already built the binaries for x64/Debug or x64/Release.

Copy the build output in \x64\[Debug|Release] to the host of the test VM and run the following in a Powershell command prompt:

1. Create a snapshot of the test VM named baseline, by running:

   Checkpoint-VM -Name <test-vm-name> -CheckpointName baseline
   

2. Store the VM administrator credential, by running the following commands:

   Install-Module CredentialManager -force
   

   New-StoredCredential -Target TEST_VM -Username <VM Administrator> -Password <VM Administrator account password> -Persist LocalMachine
   

   Note that "TEST_VM" is literal and is used in step 5 below; it need not be the name of any actual test VM.

3. Enter the \x64\[Debug|Release] directory (cd) where the build artifacts are stored.

4. Modify .\vm_list.json to specify the name of the test VM under VMList, eg:

   {
       ...
   
       "VMList":
       [
           {
               "Name": "<test-vm-name>"
           }
       ]
   }
   

5. Run the following commands to setup to use the credentials saved with TEST_VM in step 2, for logging into each of the VMs named in vm_list.json:

   Set-ExecutionPolicy unrestricted -Force
   

   .\setup_ebpf_cicd_tests.ps1
   

Installing eBPF with host-process container

The following instructions will build an ebpf-for-windows image and deploy a daemonset referencing the image. This is the easiest way to install eBPF on all Windows nodes in a Kubernetes cluster.

1. Download the .msi file from the latest release on GitHub and copy it over to images directory.

2. Build ebpf-for-windows image.

   • To build the image on the Windows Host, make sure docker is installed. Install docker on Windows Server. Start an admin Powershell on the Windows Host and run the following command and provide parameters for repository, tag and OSVersion:

     .\images\build-images.ps1
     

   • To build the image on a Linux machine (e.g. Ubuntu), make sure docker is installed (see install docker on Ubuntu), and do the following:

     • Run the following command and provide parameters for repository, tag and OSVersion:

       $HOME/ebpf-for-windows-image/build-images.sh
       

3. Push the ebpf-for-windows image to your repository.

4. Update manifests/Kubernetes/ebpf-for-windows-daemonset.yaml with the container image pointing to your image path. Run the following command:

   kubectl apply -f manifests/Kubernetes/ebpf-for-windows-daemonset.yaml