{{Header}} {{#seo: |description=Copying files into and out of {{project_name_long}} Virtual Machines. |image=Filetransfer-2126883640.png }} [[File:Filetransfer-2126883640.png|thumb|200px]] {{intro| This page describes copying files into and out of {{project_name_short}} Virtual Machines. }}
* [[File Sharing]] * [[File Transfer]] * [[USB Installation|{{project_name_short}} on USB]]
If you are interested in installation of {{project_name_short}} on USB, see [[USB Installation|{{project_name_short}} on USB]]. If you are interested in sharing files with others, see [[File Sharing]]. = Qubes-Whonix = [[Qubes|{{q_project_name_long}}]] users can utilize the usual [https://www.qubes-os.org Qubes] capabilities. Please refer to Qubes' [https://www.qubes-os.org/doc/how-to-copy-and-move-files/ copying files documentation] for further instructions. = {{non_q_project_name_short}} = {{non-q-project}} == Security Overview == '''Table:''' ''File Transfer Security Overview'' {| class="wikitable" |- ! scope="col"| '''Method''' ! scope="col"| '''Security Considerations''' |- ! scope="row"| All methods | * There is a risk of transferring [[Metadata]] or other sensitive information into {{project_name_workstation_long}}. * {{project_name_short}} is designed with isolation in mind. Isolation is weakened if data is imported from the host or other media into {{project_name_workstation_short}}, therefore this activity must be performed carefully. |- ! scope="row"| Adding Host-Only Networking adapter to {{project_name_workstation_short}} | This method is unrecommended. For further details, see: [[Whonix-Workstation_Security#Add_a_Host-Only_Networking_Adapter_/_SSH_into_Whonix-Workstation_™|Adding a Host-Only Networking Adapter to Whonix-Workstation ™ / SSH into Whonix-Workstation ™]]. |- ! scope="row"| ISO Images | * [https://www.lifewire.com/iso-file-2625923 ISO files/images] can be transferred: Host → {{project_name_gateway_long}}/Workstation. * This is the safest method of transferring files into {{project_name_workstation_short}}. |- ! scope="row"| Mounting Virtual Machine images | This method is unrecommended: * It is unknown if this procedure is feasible. * If possible, it is unclear what could possibly leak into the Virtual Machine image. * See also: [[Dev/Build Anonymity]]. |- ! scope="row"| Shared Folder | This method is currently recommended. |- ! scope="row"| SSH | * This method is only recommended for developers or experts. * File transfers work with [https://en.wikipedia.org/wiki/Secure_Shell Secure Shell Protocol (SSH)], [https://en.wikipedia.org/wiki/Secure_copy_protocol Secure Copy Protocol (SCP)] and [https://en.wikipedia.org/wiki/SSHFS SSH Filesystem (SSHFS)]; see instructions further below. |- ! scope="row" | USB devices plugged into VirtualBox | This method is unrecommended for several reasons: * Hardware serials of the USB controller and/or USB device could leak into {{project_name_workstation_short}}. * It is a security risk to plug USB controllers into untrusted virtual machines. |- |} == Transfer Files via ISO Images == This section describes how to transfer files from the host into {{project_name_gateway_short}} or {{project_name_workstation_short}} via ISO images. === Linux Host === ==== Brasero ==== Brasero is: https://en.wikipedia.org/wiki/Brasero_(software)
...a free and open-source disc-burning program for Unix-like operating systems, it serves as a graphical front-end (using GTK) to cdrtools, cdrskin, growisofs, and (optionally) libburn.
# Follow the same procedure for burning a data disk with Brasero; see [https://help.gnome.org/users/brasero/stable/project-image-burn.html.en here] and [https://www.linux.com/news/using-brasero-data-backup-and-iso-burning/ here] for instructions. # Select the option to create an ISO. # Navigate to the following area: Virtual machine window menu → Devices → CD/DVD devices → Choose a virtual disk. ==== Command line ==== [https://wiki.debian.org/genisoimage genisoimage] is a command-line tool for creating ISO filesystem images from the terminal. {{Box|text= '''1.''' Install genisoimage. {{CodeSelect|code= sudo apt install genisoimage }} '''2.''' Create an ISO "files.iso" containing the content of "folder". Replace files.iso and /path/to/folder with the preferred ISO name and suitable path to the folder content. {{CodeSelect|code= genisoimage -o files.iso /path/to/folder }} '''3.''' Mount the newly created ISO. Use the VirtualBox GUI to mount the newly created ISO which is a virtual VM CD/DVD drive. '''4.''' Create the /media/cdrom folder inside {{project_name_workstation_short}}. {{CodeSelect|code= sudo mkdir -p /media/cdrom }} '''5.''' Attach/mount the ISO to the VM. {{CodeSelect|code= sudo mount /dev/sr0 /media/cdrom }} '''6.''' Navigate into the folder. {{CodeSelect|code= cd /media/cdrom }} '''7.''' Review the files. {{CodeSelect|code= dir }} }} This procedure is intentionally one-way as the {{project_name_workstation_short}} is inherently untrusted. This way it remains isolated to prevent side-channel attacks and covert channel leaks. = KVM = See [[KVM#Shared_Folders|KVM: Shared Folders]]. = VirtualBox = == Shared Folder == {{mbox | type = notice | image = [[File:Ambox_notice.png|40px|alt=Info]] | text = This procedure is recommended. }} This method works when {{project_name_short}} is able to start normally. If {{project_name_short}} does not start properly, then another option like [[#Mount Disk Image|Mount Disk Image]] is required. Refer to the [[VirtualBox/Guest_Additions#Shared_Folder|VirtualBox Shared Folder]] entry for further details. == Mount Disk Image == The following steps are all performed inside the host operating system. ===New === [[Unspecific|unspecific to {{project_name_short}}]]. Use vboximg-mount as per upstream documentation https://www.virtualbox.org/manual/ch05.html#vboximg-mount === Old === Maybe not needed anymore. Try above method. {{Box|text= '''1.''' Shut down any running {{project_name_short}} virtual machines. * It is recommended to back-up data to avoid any potential data loss. * Never run the {{project_name_short}} VM that is currently mounted because that can lead to data loss. Always unmount first. '''2.''' {{Update}} {{CodeSelect|code= sudo apt update }} '''3.''' Install qemu. {{CodeSelect|code= sudo apt install qemu }} '''4.''' Load the Network Block Device kernel module. {{CodeSelect|code= sudo modprobe nbd max_part=16 }} '''5.''' Attach the disk image (.vmdk) to one of the newly created network block devices. The example below uses {{project_name_short}}-ws.vmdk. This is stored in the default place created by VirtualBox for VMs: /home/user/VirtualBox VMs. {{CodeSelect|code= sudo qemu-nbd -c /dev/nbd0 '/home/user/VirtualBox VMs/{{project_name_workstation_short}}/{{project_name_workstation_short}}-{{VersionNew}}-disk1.vmdk' }} sudo modprobe nbd max_part=16 is used instead of sudo modprobe nbd to avoid the following error: {{CodeSelect|code= sudo qemu-nbd -c /dev/nbd0 '/home/user/VirtualBox VMs/{{project_name_workstation_short}}/{{project_name_workstation_short}}-13.0.0.1.5-disk1.vmdk' }} {{CodeSelect|code= Failed to open /dev/nbd0: No such file or directory /build/qemu-XXUWBP/qemu-2.1+dfsq/nbd.c:nbd_receive_request ():L756: read failed }} This might relate to an old bug. https://forums.gentoo.org/viewtopic-t-822672-start-0.html '''6.''' Create a mount point. For example. {{CodeSelect|code= sudo mkdir -p /mnt/workstation }} A partition manager like cfdisk could be run on the block device, but it is more likely you will want to mount an individual partition. {{CodeSelect|code= sudo mount /dev/nbd0p1 /mnt/workstation }} The procedure is complete. A new partition with {{project_name_workstation_short}} mounted inside it will be visible. '''7.''' Unmount everything when finished. {{CodeSelect|code= sudo umount /mnt/workstation }} {{CodeSelect|code= sudo qemu-nbd -d /dev/nbd0 }} After unmounting, the {{project_name_short}} VM can be safely restarted. }} == Transfer Files via a VDI File == This section describes how to transfer files from one {{project_name_workstation_short}} to a different {{project_name_workstation_short}} via a VDI file. === Linux === The procedure below is one of the more convenient solutions for copying work from one {{project_name_workstation_short}} to another. {{Box|text= # The virtual machine that will be edited needs to be powered off. # In VirtualBox: Click on "Settings" for the {{project_name_short}} Workstation that you wish to copy files from → click on "Storage". # Select "Storage" settings → click on the square with a + sign → select "add hard disk" (located next to the "Controller: {{project_name_short}}" entry). # In the next window that appears, click on create new disk. # When prompted: Choose a "hard drive file type" → select "VDI". # When prompted: Choose "storage on physical hard drive" → select "dynamically allocated". # In the next window: Type "WhonixTransferBackup" for the drive name → choose the needed storage capacity. In many cases, the default "8.00 GB" will be enough. # After returning to the "Settings" window, click the "OK" button. # Start the {{project_name_short}} Workstation that you wish to transfer files from. After reaching the desktop, open a Terminal/Konsole session. # Format the newly created drive: {{CodeSelect|code= sudo fdisk /dev/sdb }} # At the command prompt: Type "n" create a new partition → press "enter" to choose the default options when prompted until returned to fdisk's main menu → type "w" to write the partition and exit fdisk. # In the terminal session, type: {{CodeSelect|code= sudo mkfs.ext4 /dev/sdb1 }} # Create a new directory to be the mount point for the drive: {{CodeSelect|code= mkdir temp }} # Mount the new drive: {{CodeSelect|code= sudo mount /dev/sdb1 temp }} # Change the permissions of the mount folder so it is possible to write to the drive: {{CodeSelect|code= sudo chmod 777 temp }} # Copy selected files to the new drive by copying them to the "temp" folder. This is possible in the terminal, with the file browser and so on. Once all files have been copied to the "temp" folder, shut down the {{project_name_short}} Workstation. # After the {{project_name_short}} Workstation has closed, open the "Virtual Media Manager" in VirtualBox: Click on "File → Virtual Media Manager". # Locate the new VDI file created in steps 2-8 → click on it → click the "copy" button → click the "next" button. # When prompted to choose a "hard drive file type," select "VDI". # When prompted to choose "storage on physical hard drive," select "dynamically allocated". # In the next window: type "WhonixWorkstationFileTransfer" for the drive name → choose a folder to store the VDI file → click on the "copy" button. If copying does not work, power down the old VM and attach the same VDI to the new VM. # After returning to the "Virtual Media Manager" window, click the "close" button. # In the main VirtualBox window: Click the {{project_name_short}} Workstation version that you want to copy the files into → click "settings". # Navigate to the "storage" section → click on the square with a + sign → select "add hard disk" (located next to the "Controller: {{project_name_short}}" entry). # In the next window: Click on "choose existing disk" → find the saved "WhonixWorkstationFileTransfer.vdi" file and select it. # After returning to the "settings" window, click "OK." # Start the {{project_name_short}} Workstation that you wish to copy your files into. After reaching the desktop, open a Terminal/Konsole session. # Create a new directory to be the mount point for the drive:{{CodeSelect|code= mkdir temp }} # Mount the new drive: {{CodeSelect|code= sudo mount /dev/sdb1 temp }} # Finally, copy selected files into the {{project_name_short}} Workstation. When copying is finished, shut down the {{project_name_short}} Workstation and delete the temporary "file transfer" VDI files through Virtual Media Manager. }} Related forum topic:
[https://forums.whonix.org/t/solved-how-to-tranfer-data-to-whonix-8/115 How to tranfer data to {{project_name_short}} 8] === Windows === Refer to the following forum topic: [https://forums.whonix.org/t/virtualbox-transfer-files-from-whonix-to-host-with-disk-images/2189 Virtualbox: Transfer files from {{project_name_short}} to host with disk images]. == Add a USB Device to VirtualBox == {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = This procedure is not recommended for security reasons. A malicious guest can flash the low level firmware of the USB thumb drive, turning it into an attack vehicle against any machine it is plugged into. }} By default, Oracle VirtualBox only supports USB 1.1. Additional, closed source extension packs exist for better USB support such as versions 2.0 and 3.0; they can be downloaded from the [https://www.virtualbox.org/wiki/Downloads VirtualBox download page]. Note that improved USB support does not require VirtualBox Guest Additions. It is unclear whether a reboot is required after installation of the extension pack(s); refer to the official VirtualBox documentation for additional information: * [https://www.virtualbox.org/manual/ch01.html#intro-installing Installing Oracle VM VirtualBox and Extension Packs] * [https://www.virtualbox.org/manual/ch03.html#settings-usb USB Support] Since [[About#Based_on_Debian|{{project_name_short}} is based on Debian]], any additional research that is required can utilize search terms like "How to get USB in Linux VirtualBox?". See also: [[Self_Support_First_Policy|Self Support First Policy]]. {{Box|text= '''1.''' Adjust the Linux user group. For Linux hosts, the user that is running VirtualBox must be a member of linux user group vboxusers. Otherwise VirtualBox GUI will show no devices available. To add the current user to group vboxusers, run. {{CodeSelect|code= sudo adduser $(whoami) vboxusers }} '''2.''' Reboot. A reboot or re-login is required. '''3.''' Plug in the USB device. USB devices are plugged into Virtual Machines through the device menu in VirtualBox. '''4.''' Mount the USB device. Automount of USB devices is disabled in {{project_name_short}} by default. To mount the device, try: Start menu → System Settings → Removable Media or manually mount the device. Failures or successes can also be shared in [https://forums.{{project_clearnet}} a new forum discussion]. '''5.''' ''Optional'': Install the ntfs-3g package. If the USB device is formatted with NTFS, it is necessary to install the [https://tracker.debian.org/pkg/ntfs-3g ntfs-3g driver package] and run a special mount command, see: [https://forums.whonix.org/t/can-t-enable-usb-drive-in-virtualbox-troubleshooting-help-needed/1563/7 Can’t enable USB Drive in VirtualBox – troubleshooting help needed]. }} == SSH into {{project_name_gateway_short}} == {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = Developers / experts only! Only for debugging! }} These instructions assume a connection from a local host into {{project_name_short}}, not SSH to a remotely running {{project_name_short}} instance. {{Box|text= '''1.''' Adjust {{project_name_gateway_short}} firewall settings. {{Firewall_Settings_Gateway}} '''2.''' Add. 
GATEWAY_ALLOW_INCOMING_SSH=1
'''3.''' Restart the firewall. {{Reload Firewall}} '''4.''' Install openssh-server inside {{project_name_gateway_short}}. Make sure this is run on {{project_name_gateway_short}}! Run the command once. {{CodeSelect|code= sudo apt install openssh-server }} '''5.''' Add port forwarding from host into the virtual machine. Make sure this is run on the host! Run the command once. Open a terminal. This will forward connections from the host to 127.0.0.1:2200 to the SSH server running inside {{project_name_gateway_short}} on port 22. {{CodeSelect|code= VBoxManage modifyvm "{{project_name_gateway_short}}" --natpf1 "ssh",tcp,127.0.0.1,2200,,22 }} If it is necessary to undo this change, run. {{CodeSelect|code= VBoxManage modifyvm "{{project_name_gateway_short}}" --natpf1 delete "ssh" }} To verify the change, run. {{CodeSelect|code= VBoxManage showvminfo "{{project_name_gateway_short}}" }} Search for lines beginning with NIC. For example: 
NIC 1 Rule(0):   name = ssh, protocol = tcp, host ip = 127.0.0.1, host port = 2222, guest ip = 127.0.0.1, guest port = 22
'''6.''' Open a SSH session on the host. Make sure this is run on the host! As user. {{CodeSelect|code= ssh user@127.0.0.1 -p 2200 }} Or as root. {{CodeSelect|code= ssh root@127.0.0.1 -p 2200 }} '''7.''' Create a folder which will be used to mount the image. Perform this step on the host or mount {{project_name_gateway_short}} as a folder. This folder must exist before trying to mount. {{CodeSelect|code= mkdir ~/mountgateway }} '''8.''' Mount the folder. Make sure this is run on the host! As user. {{CodeSelect|code= sshfs user@127.0.0.1:/ -p 2200 ~/mountgateway }} Or as root. {{CodeSelect|code= sshfs root@127.0.0.1:/ -p 2200 ~/mountgateway }} }} == SSH into {{project_name_workstation_short}} == === Introduction === {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = Developers / experts only! Only for debugging! }} These instructions assume a connection from a local host into {{project_name_short}}, not SSH to a remotely running {{project_name_short}} instance. The connection formed will look like this: host → SSH → {{project_name_gateway_short}} → SSH → {{project_name_workstation_short}}. It is not possible to directly SSH into {{project_name_workstation_short}} because it only has an internal network interface and no NAT interface. Adding a NAT interface would defeat the purpose of {{project_name_short}}. === Prerequisite === Do not attempt this procedure before mastering the steps [[#SSH_into_Whonix-Gateway|SSH into {{project_name_gateway_short}}]]. === Firewall === {{Box|text= '''1.''' Adjust {{project_name_workstation_short}} firewall settings. {{Firewall_Settings_Workstation}} '''2.''' Add the necessary port. Replace 80 with the actual port that should be opened. {{CodeSelect|code= EXTERNAL_OPEN_PORTS+=" 80 " }} Save. '''3.''' {{Reload_Firewall_ws}} }} === Setup Workstation === On {{project_name_workstation_short}}, run. {{CodeSelect|code= sudo apt install openssh-server }} Notes if using a {{project_name_customworkstation_short}}: * Some Linux distributions only install the server service by default but do not enable/start it by default. In that case, it is up to the user to start the service. * Make sure it listens not only on localhost. It must listen on the external interface (or all interfaces) too. === Setup Gateway === On {{project_name_gateway_short}}, run. sudo -u tunnel is required because user user on {{project_name_gateway_short}} is not supposed to be used for (virtual) local LAN activity as per Whonix firewall. Note: root@ can also be substituted for user@ or similar in following command. {{CodeSelect|code= sudo -u tunnel ssh.anondist-orig root@10.152.152.11 }} === Setup Host === Note: * It is possible to use one command to SSH from the host into {{project_name_gateway_short}} and then SSH into {{project_name_workstation_short}}. This is called SSH hopping. * SSH hopping is also possible for SSHFS; see [https://www.larkinweb.co.uk/computing/mounting_file_systems_over_two_ssh_hops.html here]. * The filesystem of {{project_name_workstation_short}} can also be mounted with two commands. {{Box|text= '''1.''' SSH from the host into {{project_name_gateway_short}}. host → {{project_name_gateway_short}} {{CodeSelect|code= ssh -t user@127.0.0.1 -p 2200 "sudo -u tunnel ssh.anondist-orig user@10.152.152.11" }} {{Code|root@}} can also be substituted in the above command. '''2.''' Create a directory to mount {{project_name_workstation_short}}. {{CodeSelect|code= mkdir ~/mountworkstation }} '''3.''' SSH into {{project_name_workstation_short}} and map to localhost:2222. {{project_name_gateway_short}} → {{project_name_workstation_short}} Perform this step on the host. {{CodeSelect|code= ssh -f user@127.0.0.1 -p 2200 -L 2222:10.152.152.11:22 -N }} {{Code|root@}} can also be substituted in the above command. '''4.''' Mount the {{project_name_workstation_short}} folder on the host. {{CodeSelect|code= sshfs -p 2222 user@127.0.0.1:/ ~/mountworkstation }} If these instructions did not work, try the alternative standalone instructions [[Sshfs into {{project_name_workstation_short}}|SSHFS into Whonix-Workstation]]. }} == Usability Development Tickets == All solutions listed here are far from user friendly. Help is most welcome to improve this situation. Please refer to existing tickets about this issue: * [https://phabricator.whonix.org/T21 {{project_name_short}} Host Additions] = See Also = * {{kicksecure_wiki |wikipage=Backup_VMs |text=Backup {{project_name_short}} VMs }} = Footnotes = {{reflist|close=1}} {{Footer}} [[Category:Documentation]] [[Category:Development]]