└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Winmin Prerelease Setup 2 | 3 | ## Background 4 | 5 | Winmin (working title) is a set of tools and scripts that facilitate using Windows applications on Linux using a kvm virtual machines and libvirt. Winmin was originally inspired by a [tweet](https://twitter.com/unixterminal/status/1255919797692440578) from [Hayden Barnes](https://twitter.com/unixterminal) in which he demonstraited running Microsoft Word on Ubuntu 20.04. Since then I have worked to replicate this setup and make various tools that make using it easier. 6 | 7 | ## Preparation 8 | 9 | Install packages and setup groups 10 | 11 | ``` 12 | $ sudo apt -y install spice-client-gtk libvirt-clients libvirt-daemon-system virtinst python3 python-is-python3 python3-magic samba wimtools 13 | 14 | $ sudo usermod -aG kvm,tty $USER 15 | ``` 16 | You may need to logout or reboot in order for group changes to take effect. You can check your current groups with the `groups` command. 17 | 18 | Set default libvirt uri to system. 19 | ``` 20 | $ echo "export LIBVIRT_DEFAULT_URI=\"qemu:///system\"" >> $HOME/.bashrc 21 | $ source $HOME/.bashrc 22 | ``` 23 | 24 | # Setting up Winmin 25 | 26 | Download the latest deb packages for each winmin component in the releases section of its repository. 27 | 28 | - [winmin-viewer](https://github.com/vlinkz/winmin-viewer/releases) 29 | - [winmin-tools](https://github.com/vlinkz/winmin-tools/releases) 30 | - [winmin-autosetup](https://github.com/vlinkz/winmin-autosetup/releases) 31 | 32 | Once downloaded, install them with dpkg 33 | 34 | ``` 35 | $ sudo dpkg -i winmin-viewer_0.1-1_amd64.deb winmin-tools_0.1-1_amd64.deb winmin-autosetup_0.1-1_amd64.deb 36 | ``` 37 | If you are not using a Ubuntu based distribution, you can build and install the packages manually as described in each repository's readme. 38 | 39 | Run the winmin setup application from the command line. You will need to input a Windows 10 iso (May 2020 update or later only). Replace `XXXXX-XXXXX-XXXXX-XXXXX-XXXXX` with your Windows product key. If no virtio-win iso is specifed, the script will download the latest version. 40 | 41 | ``` 42 | $ winmin-autosetup ./Win10.iso XXXXX-XXXXX-XXXXX-XXXXX-XXXXX ./virtio-win.iso 43 | ``` 44 | A virtual machine will be created. You will be able to see Windows being set up, but no user input is required. 45 | 46 | Once finished, head over to the [winmin-pkgs](https://github.com/vlinkz/winmin-pkgs) repo to find yaml packages. Feel free to submit PRs with new packages or request them in the issues section. 47 | 48 | # Installing Packages 49 | 50 | To install a package, use the `winmin-yml-install` command or the `winmin-install` command. See the [winmin-tools](https://github.com/vlinkz/winmin-tools) repo for details on how to install packages. 51 | 52 | __IMPORTANT__: When installing an application, before closing the installation window, RUN THE PROGRAM(S) YOU INTEND TO USE AT LEAST ONCE. Currently both the ms-office and visualstudio packages are set to destroy the vm (revert back to the previous save state) on exit, this means any configuration changes made to the application will not be saved between uses. This can be changed by setting the `--save` flag in each application's `.desktop` file, however it is not set by default as closing an application will take around 10-15 seconds. Also, before exiting the installer CLOSE ALL WINDOWS INCLUDING THE INSTALLER. This will probably be automated later when I get around to it. 53 | 54 | __IMPORTANT__: Currently, running two applications from the same package (or VM) at once is "impossible". For example, if I have Word open, and a launch Excel, the Word window will freeze and the Excel will be launched on top of Word in the new window. When you close the frozen Word window, the VM will be saved or destroyed and the Excel window will freeze. I'm working on a fix using multiple monitors, stay tuned (see: [winmin-viewer-multimonitor](https://github.com/vlinkz/winmin-viewer/blob/master/winmin-viewer-multimonitor.c)). 55 | 56 | # Issues 57 | 58 | Please report an issues encountered in the repository of the respective tool that did not work. 59 | 60 | If you have questions about the project as a whole, or any suggestions, you can create an issue on this repository or contact me on [twitter](https://twitter.com/VlinkZ3). 61 | 62 | Note: Outlook sometimes complains about `C:\Users\VM\AppData\Local\Microsoft\Outlook\email@address.com.ost` being outdated. After installing ms-office, before closing the window, delete this file. I will probably add a prefix command that deletes this file soon. 63 | 64 | # Development Setup 65 | 66 | ## Tools 67 | 68 | To work on developing this set of tools, I highly recommend you install `virt-manager`. This tool allows you to manage and edit libvirt virtual machines. 69 | 70 | If you shutdown or reboot a Winmin virtual machine, after booting, open the terminal and run 71 | ``` 72 | $ virsh console winmin-{vm} 73 | 74 | SAC> cmd 75 | 76 | SAC> ch -sn Cmd001 77 | 78 | C:\Windows\system32> ^] 79 | ``` 80 | 81 | This sets up the virtual machine in a state where it can receive commands. 82 | 83 | # How Winmin works 84 | 85 | ## Basics 86 | 87 | Winmin works by installing Windows applications into virtual machines, and then starting a virtual machine, executing the application, and then displaying it using a remote desktop viewer. 88 | 89 | ## In depth (WIP) 90 | 91 | ### Initial Setup 92 | 93 | When running `winmin-autosetup`, a python script executes commands to create a libvirt virtual machine named `winmin-base`. After the installation is completed, this virtual is shut down and never directly used again. This machine works as a base image where all other virtual machine with applications installed are derived from. It is important to make this image as small and lightweight as possible in order to have good performance. 94 | 95 | When setting up the vm, the [Windows Emergency Management Services and Serial Console](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc787940(v=ws.10)?redirectedfrom=MSDN) is installed. This allows Winmin tools to interact directly with the Windows guest's serial interface and execute commands quickly. 96 | 97 | ### Installing Applications 98 | 99 | When an application is installed with either `winmin-yml-install` or `winmin-install`, a new virtual machine is created. A new virtual hard drive is created which uses the `winmin-base` image as its [backing file](https://libvirt.org/kbase/backing_chains.html). Using this technique, when an application is installed, the new disk only takes up as much additional space as the size of the application. 100 | 101 | Once the user installs the application, the state of the vm is [saved](https://libvirt.org/docs/libvirt-appdev-guide-python/en-US/html/libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save.html). Every time a user launches the application, the save state is resumed and the application is executed. 102 | 103 | ### Running Applications 104 | 105 | When an application is started, it's virtual machine is started from the last save state. Commands are sent to the serial port and are executed in the guest. The SPICE socket is located and `winmin-viewer` is executed to display the application. Any file arguments are converted to their respective addresses on the host's samba server so that the guest can access and edit them. When an application window is closed, the virtual machine is either saved or destroyed (reverted back to its previous save state). 106 | --------------------------------------------------------------------------------