diff --git a/PROXY_GUIDELINE.md b/PROXY_GUIDELINE.md new file mode 100644 index 0000000..a1770db --- /dev/null +++ b/PROXY_GUIDELINE.md @@ -0,0 +1,168 @@ + + +# Proxy Guideline + +If you're using OSWorld behind a GFW, you can configure your VM to use proxy +following the steps below. + +#### 1. Configure Your Proxy on the Host Machine + +By default, proxy software usually listens only to the local loopback address +(`127.0.0.1`), which cannot be reached from other machine (including the +virtual machine). Hence, firstly make your local proxy software listen to the +IP address of the VMWare network card, or simply `0.0.0.0` for all the IP +addresses. The VMWare network card are usually named `vmnetX` like `vmnet8`. +Make sure to use the IP address within the identical network segment. For +example, `192.168.108.1/24` and `192.268.108.130/24` are within the same +network segment, *i.e.*, the same subnet mask (24) and the same prefix +(`192.168.108`, 24-bit length). Usually, different VM instances share the same +network segment, and so, the effective host IPs are the same. + + After launching the VM, you can use + +```sh +# run this command on host +# change ws to fusion if you use VMWare Fusion +vmrun -T ws getGuestIPAddress /path/to/vmx/file +``` + +to get the IP of the VM. As for host IPs, on Ubuntu (Linux) machine, you can +use `ip a` command to check the IP addresses of each network card. On Windows +machine, you can use `ipconfig` command to check the IP addresses of each +network card. Recognize the correct IP and note it for later use. + +Then you should configure the listening address of your proxy software: + +![host proxy setting](assets/proxysetup.png) + +If you cannot change the listening address of your proxy software, you can set +up port forwarding. Suppose your proxy software is listening to 1080 port of +localhost (`127.0.0.1`), and the effective host IP address is `192.168.108.1`. +On Ubuntu (Linux), you can use `socat` to forward `192.168.108.1:1080` to +`127.0.0.1:1080`: + +```sh +socat TCP-LISTEN:1080,bind=192.168.108.1,fork TCP:127.0.0.1:1080 +``` + +On Windows, if you have administrative privilidge, you can simply run the +following command in a `cmd` window with admin privilidge. + +```bat +netsh interface portproxy add v4tov4 listenaddress=192.168.108.1 listenport=1080 connectaddress=127.0.0.1 connectport=1080 +``` + +Or if you haven't got administrative privilidge, you can use `ncat` bundled in +[Nmap](https://nmap.org) to forword the port: + +```bat +ncat -k -l 192.168.108.1 1080 --sh-exec 'ncat 127.0.0.1 1080' +``` + +#### 2. Configure in the VM Machine + +##### For the Ubuntu Image + +###### Configuration by GUI + +Open system network setting in the VM. + +![open setting](assets/netsetting1.png) + +![open network setting](assets/netsetting3.png) + +Then, click on "Network Proxy". + +![proxy setting](assets/netsetting4.png) + +Set an appropriate proxy mode. Usually, use "Manual" mode, and set the correct +IP addresses and ports. The IP address should be the host machine IP noted in +the previous step. + +Then you can open a chrome page to check if the proxy works well. + +###### Configuration by Command Line + +If configuration by GUI is not suitable for you, you can instead execute the +following commands in the VM to configure proxy on the Ubuntu image: + +```sh +# run these command in the VM +gsettings set org.gnome.system.proxy mode 'manual' +gsettings set org.gnome.system.proxy.http host 'xxx.xxx.xxx.xxx' +gsettings set org.gnome.system.proxy.http port xxxx +gsettings set org.gnome.system.proxy.https host 'xxx.xxx.xxx.xxx' +gsettings set org.gnome.system.proxy.https port xxxx +gsettings set org.gnome.system.proxy.socks host 'xxx.xxx.xxx.xxx' +gsettings set org.gnome.system.proxy.socks port xxxx +``` + +If there isn't a physical or virtual screen available for you to direct operate +on the VM, you can run these commands with the help of `vmrun`. For instance, + +```sh +# run this command on host +# change ws to fusion if you use VMWare Fusion +vmrun -T ws runProgramInGuest /path/to/vmx/file /usr/bin/gsettings set org.gnome.system.proxy mode 'manual' +``` + +##### For Window Image + +###### Configuration by GUI + +Open system network setting in the VM. + +![open setting](assets/winnetsetting1.png) + +![open network setting](assets/winnetsetting2.png) + +Then, click on "Proxy". + +![proxy setting](assets/winnetsetting3.png) + +Switch on "Use a proxy server" and type in the correct proxy configurations. + +![proxy setting](assets/winnetsetting4.png) + +Finally, remember to click on "Save". + +Note that only HTTP proxy is supported. Subsequently, you can open a chrome +page to check if the proxy works well. + + + +#### 3. Create a New Snapshot + +After modifying the virtual machine, remember to create a new snapshot and +start from this new snapshot at experiments. + +```sh +# change ws to fusion if you use VMWare Fusion +vmrun -T ws snapshot /path/to/vmx/file snapshot_name +``` + +```python +env = DesktopEnv(snapshot_name="snapshot_name") +``` diff --git a/README.md b/README.md index 5489bd2..0a5aac5 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,9 @@ Afterward, you can execute a command similar to the one in the previous section \*No environment parallelism. Calculated in April 2024. +### How can I configure a proxy for the VM if I'm behind a GFW? + +See [Proxy Guideline](PROXY_GUIDELINE.md) ## 📄 Citation If you find this environment useful, please consider citing our work: diff --git a/assets/netsetting1.png b/assets/netsetting1.png new file mode 100644 index 0000000..4c6651b Binary files /dev/null and b/assets/netsetting1.png differ diff --git a/assets/netsetting2.png b/assets/netsetting2.png new file mode 100644 index 0000000..17b7650 Binary files /dev/null and b/assets/netsetting2.png differ diff --git a/assets/netsetting3.png b/assets/netsetting3.png new file mode 100644 index 0000000..df2e95f Binary files /dev/null and b/assets/netsetting3.png differ diff --git a/assets/netsetting4.png b/assets/netsetting4.png new file mode 100644 index 0000000..b0f9fbb Binary files /dev/null and b/assets/netsetting4.png differ diff --git a/assets/proxysetup-zh.png b/assets/proxysetup-zh.png new file mode 100644 index 0000000..69b5e81 Binary files /dev/null and b/assets/proxysetup-zh.png differ diff --git a/assets/proxysetup.png b/assets/proxysetup.png new file mode 100644 index 0000000..605f6e9 Binary files /dev/null and b/assets/proxysetup.png differ diff --git a/assets/winnetsetting1.png b/assets/winnetsetting1.png new file mode 100644 index 0000000..b2ac6af Binary files /dev/null and b/assets/winnetsetting1.png differ diff --git a/assets/winnetsetting2.png b/assets/winnetsetting2.png new file mode 100644 index 0000000..e854e53 Binary files /dev/null and b/assets/winnetsetting2.png differ diff --git a/assets/winnetsetting3.png b/assets/winnetsetting3.png new file mode 100644 index 0000000..d85d50f Binary files /dev/null and b/assets/winnetsetting3.png differ diff --git a/assets/winnetsetting4.png b/assets/winnetsetting4.png new file mode 100644 index 0000000..cc0105f Binary files /dev/null and b/assets/winnetsetting4.png differ