Charles web debugging proxy linux

Charles

Web Debugging Proxy Application for Windows, Mac OS and Linux

Download

Browser & System Configuration

In order for any browser (or any application) to use Charles it must be configured to use Charles as its proxy server. Most browsers will have a way to configure this manually, but configuring manually is annoying because you have to configure and reconfigure everytime you start and stop Charles.

Fortunately Charles can autoconfigure the proxy settings in many cases including:

• Windows / Internet Explorer proxy settings – used automatically by most Windows applications
• macOS proxy settings – used automatically by most macOS applications
• Mozilla Firefox proxy settings (all platforms)

Windows Proxy Settings

Charles can automatically configure the Windows proxy settings so that Internet Explorer and other Windows applications automatically start using Charles. By default Charles will configure and then reconfigure the Windows proxy settings whenever Charles is started or quit.

Charles proxy configuration behaviour can be changed in Charles in the Proxy Menu, Proxy Settings dialog.

The Windows proxy settings are configured in the Internet Options control panel on the Connections tab if you want to look at them yourself.

Microsoft Edge has an additional setting that you may need to make by browsing to about:flags and enabling Allow localhost loopback. This is required in order to connect to Charles Proxy running on localhost.

macOS Proxy Settings

Charles can automatically configure the macOS system proxy settings so that Safari and other macOS applications automatically start using Charles.

When you first install Charles you will be prompted to grant permissions to Charles to autoconfigure the proxy settings. After that, Charles will configure and then reconfigure the macOS proxy settings whenever Charles is started or quit.

Charles proxy configuration behaviour can be changed in Charles in the Proxy Menu, Proxy Settings dialog.

The macOS proxy settings are configured in the advanced areas of the Network panel in the System Preferences if you want to look at them yourself.

In order to use HTTP 2 with Charles from Safari you must use Charles in SOCKS mode. See the Proxy Settings for configuring SOCKS.

iOS Device Settings

To use Charles as your HTTP proxy on your iPhone you must manually configure the HTTP Proxy settings on your WiFi network in your iPhone’s Settings.

Go to the Settings app, tap Wi-Fi, find the network you are connected to and then tap it to configure the network. Scroll down to the HTTP Proxy setting, tap Manual. Enter the IP address of your computer running Charles in the Server field, and the port Charles is running on in the Port field (usually 8888). Leave Authentication set to Off.

All of your web traffic from your iPhone will now be sent via Charles. You should see a prompt in Charles when you first make a connection from the iPhone, asking you to allow the traffic. Allow this connection. The IP address of your iPhone will be added to the Access Control list in Charles, which you can view and change in the Proxy menu > Access Control Settings.

Remember to disable the HTTP Proxy in your Settings when you stop using Charles, otherwise you’ll get confusing network failures in your applications!

Auto configuration

You can also supply an auto-configuration URL instead of entering manual configuration. This approach will enable your device to first try to use Charles, but then to fallback to using a direct connection if Charles isn’t running. This is an experimental approach!

For the auto-configuration URL enter:

Where you replace X.X.X.X with the IP address of your computer running Charles. This defaults to port 8888. If you use a different port, just include that, e.g. https://chls.pro/X.X.X.X:XXXX.pac

You can also use Charles in SOCKS proxy mode from iOS using an autoconfiguration rule, in spite of this not being available as a manual setting. Enter the auto-configuration URL as follows:

HTTP 2

Safari on iOS 10 does not currently support HTTP 2 via HTTP proxies. In order to use HTTP 2 with Safari on iOS and Charles Proxy you need to use Charles in SOCKS mode and use the auto-configuration URL described above to specify SOCKS mode.

iOS Simulators

The iOS Simulator should use the system proxy settings. If it doesn’t, please try quitting and restarting the iOS Simulator. As of Xcode 6 it appears to be important that Charles is running and set as the macOS system proxy before you run the iOS Simulator.

Mozilla Firefox Proxy Settings

Configure Firefox to use your system proxy settings. In Firefox, go to Preferences > Advanced > Network > Connection Mozilla Firefox can now be configured to use the system proxy settings, which is usually preferable as Charles can control the system proxy settings on Windows and macOS without the need for installing an add-on. Check your Firefox proxy settings in Preferences > Advanced > Network > Connection and press the Settings button. Then choose «Use system proxy settings».

Manual Proxy Configuration

In Charles, go to the Proxy menu and choose Proxy Settings. This will show you the currently configured HTTP Proxy Port and SOCKS Proxy Port. Note down which one you want to use (probably HTTP Proxy).

The host name is 127.0.0.1 (your own computer) or the external address of your computer if you want to access Charles from another computer.

You can then configure your browser or application’s proxy settings with that host name and port.

Java Application Proxy Configuration

You can configure your Java application to use Charles in code or as command line arguments to the java executable.

System.setProperty(«http.proxyHost», «127.0.0.1»);
System.setProperty(«http.proxyPort», «8888»);

And for HTTPS as well. Note that you may also want to configure Java to trust Charles’s root certificate in this case (see SSL Proxying).

System.setProperty(«https.proxyHost», «127.0.0.1»);
System.setProperty(«https.proxyPort», «8888»);

For the source of this information, including more discussion and how to set these as command line arguments: http://java.sun.com/j2se/1.5.0/docs/guide/net/proxies.html

cURL and libcurl

For cURL on the command line:
curl —proxy localhost:8888

If you are developing an application using libcurl you can configure it to use Charles as its proxy server:

curl_easy_setopt(pCurl, CURLOPT_PROXY, «127.0.0.1»);
curl_easy_setopt(pCurl, CURLOPT_PROXYPORT, 8888);

If you are using SSL you may like to disable the certificate verification during development, if you can’t get cURL to trust Charles’s CA certificate:

curl_easy_setopt(pCurl, CURLOPT_SSL_VERIFYPEER, 0);

Thanks to Michael Klische for providing this information.

Android emulator

In the Android emulator run configuration add an Additional Emulator Command Line Option:
-http-proxy http://10.0.2.2:8888

Where 10.0.2.2 is a special IP address for Android Emulators that resolves to the host computer IP. If you run Charles on another computer, replace that IP address with the IP address of the other computer.

Android

Some Android devices have HTTP proxy settings. On the Nexus S it is hidden; you can access the HTTP proxy settings by opening the Voice Dialler app and saying «proxy». On some Samsung devices you can access proxy settings by long-pressing on the network name in the WiFi configuration.

You can also hardcode your application to use a proxy server during testing:

HttpHost httpproxy = new HttpHost(«192.168.0.101», 8888, «http»);
httpClient.getParams().setParameter(ConnRoutePNames.DEFAULT_PROXY,httpproxy);

HttpUrlConnection conn = url.openConnection(new Proxy(Proxy.Type.HTTP, new InetSocketAddress(«192.168.0.101», 8888)));

Make sure the first IP address is the IP address of your computer running Charles, then add this code to customise your httpClient or to open a URL connection.

Charles is developed by XK72. All content is copyright 2021. Site design by Matthew Buchanan.

Источник

Charles

Web Debugging Proxy Application for Windows, Mac OS and Linux

Download

APT repository

Charles has an APT repository for Debian-based Linux distributions.

NB: The keys for the repo changed on 26 July 2016, to utilise a larger key size and stronger digests. Existing users of the APT repository will need to import the new public key. The new public key is at the same URL as the old public key, therefore repeat the apt-key add step below to add it. Finally, run apt-get update to use the new key.

First install the GPG public key for the repository so you can verify that the packages are correctly signed. The current public key id is 1AD28806 and its fingerprint is 4BA7 DB85 7B57 0089 7420 96E1 5F16 B97C 1AD2 8806:

Then add the repository to your sources:

sudo sh -c ‘echo deb https://www.charlesproxy.com/packages/apt/ charles-proxy main > /etc/apt/sources.list.d/charles.list’

Then update your sources and install Charles:

The package creates a «charles» command in /usr/bin, and adds Charles in your application menus in your window manager.

You may also install the beta track of Charles which is called charles-proxy-beta.

Charles 3

To install Charles 3, use the package charles-proxy3. You can have both Charles 4 and Charles 3 installed at the same time.

The package creates a «charles3» command in /usr/bin, and adds Charles in your application menues in your window manager.

Charles is developed by XK72. All content is copyright 2021. Site design by Matthew Buchanan.

Источник

Charles

Web Debugging Proxy Application for Windows, Mac OS and Linux

Download

General

Some systems are hard coded to not use proxies for localhost traffic, so when you connect to http://localhost/ it doesn’t show up in Charles.

The workaround is to connect to http://localhost.charlesproxy.com/ instead. This points to the IP address 127.0.0.1, so it should work identically to localhost, but with the advantage that it will go through Charles. This will work whether or not Charles is running or you’re using Charles. If you use a different port, such as 8080, just add that as you usually would, e.g. localhost.charlesproxy.com:8080.

You can also put anything in front of that domain, e.g. myapp.localhost.charlesproxy.com, which will also always resolve to 127.0.0.1.

Alternatively you can try adding a ‘.’ after localhost, or replace localhost with the name of your machine, or use your local link IP address (eg. 192.168.1.2).

If Charles is running and you’re using Charles as your proxy, you can also use local.charles as an alternative for localhost. Note that this only works when you’re using Charles as your proxy, so the above approaches are preferred, unless you specifically want requests to fail if not using Charles.

Please check that the character encoding or charset is correctly set by the server, otherwise Charles will guess and may not guess correctly.

You may also need to choose a font that can display the charset in the response. You can change the font used in the Preferences on the User Interface tab. You will need to restart Charles for those changes to take effect.

Charles uses Java so you need to have a Java Runtime Environment installed. You can download Java from Oracle.

If you are using the 32 bit version of Charles you must have a 32 bit JRE installed, and vice versa if you’re using the 64 bit version of Charles you must have a 64 bit JRE installed.

If you have the correct JRE installed and you still get a «Failed to find Java VM» message, please try reinstalling Java – if Charles can’t find your JRE then it is likely that your registry contains some invalid details, which reinstalling will correct. Also note that Charles requires a JRE and will not run if you only have the JDK installed. When you install the JDK it will offer to install a JRE as well, so this is usually not an issue.

It is likely that your browser’s proxy settings have been changed to use Charles and then, for some reason, not changed back.

First try starting and quiting Charles normally to see if that corrects the problem. Because if Charles is stopped abnormally (such as a crash) it doesn’t have an opportunity to reset your proxy settings. It should notice that when it is restarted.

If that doesn’t work you’ll need to fix your proxy settings manually. How you do this depends on what application is misconfigured:

Windows / Internet Explorer
First quit Charles. Then go to the Internet Options in your Control Panel. Go to the Connections tab. Click on the LAN Settings. You’ll see a Proxy panel. Uncheck the Use a Proxy checkbox. Click OK until you’ve closed the Internet Options.

Mac OS X
Go to your System Preferences. Open the Network preferences. Choose the appropriate Network Port (you may need to reconfigure more than one if you have more than one) and click Configure. Go to the Proxies tab. Look in the list of proxy servers, you will see that Web Proxy and Secure Web Proxy are active. Uncheck those or reconfigure them as required for your network. Click Apply Now and then close the Network preferences.

Firefox
First quit Charles. Then go to the Firefox Preferences window, General tab, click Connection Settings. Then choose “Direct Connection to the Internet” or enter whatever proxy settings are required for your network. Click OK and then close the Preferences window.

Crashes are fortunately unusual! There are a few things that might be causing it, or will help me diagnose and hopefully fix the problem.

Known Problems

Below is a list of problems that I know about with Charles that you might be having, and the recommended solution:

NOD32 IMON

If you’re running the NOD32 antivirus package and have its IMON service running, you are likely to encounter crashes in Charles – one moment Charles will be running normally and the next it will have just disappeared, leaving your browser broken as it hasn’t corrected your proxy settings (fortunately restarting Charles will remedy that).

There is no fix from NOD32 at this time, so you need to either disable IMON or exclude Charles from it. The later being the preferred option as you continue to benefit from IMON – although you may also find that it interferes with other applications.

Excluding Charles from IMON
We need to add Charles to the exclusions list in order to exclude Charles. Charles is a Java application, so adding the Charles.exe application to the exclusions won’t help: instead you need to add the Charles.exe inside the launch4j-tmp directory in your JRE directory.

Open the NOD32 Control Centre, click on IMON, click on the Setup button to enter IMON Setup.

Go to the Miscellaneous tab and look for the Exclusion panel. Click the Edit. button in the Exclusion panel. The Exclude applications dialog will appear.

Click the Add. button. Find your Java installation. This is probably in C:Program FilesJavajre* where the * is a version number. If you have multiple JREs installed check which version Charles is using (use About Java in the Help menu). Inside the JRE folder will be a launch4j-tmp folder, in which will be the Charles.exe that you need to exclude.

Reporting A Crash

If your problem isn’t described above then please report it to me. What will be a great starting point is if you can send:

• Your OS name and version (eg. Windows XP SP2)
• The version of Java that you’re running Charles in, as reported by the About Java option in the Help Menu
• Look for any Java crash logs that have been created in the Charles directory (eg. C:\Program Files\Charles ), they will be named hs_err_pid###.log. Please copy and paste one of these into the email.

Finally send all of that to me using the Contact page.

Charles supports NTLM authenticating websites. You can access NTLM authenticating websites through Charles without any problems.

NTLM authentication is also known as “Windows NT Challenge Response” and “Integrated Windows Authentication” and is mainly used in conjunction with IIS.

NOTE You have to use HTTP 1.1 in order to use NTLM authentication through Charles. See more information on configuring your web browser to use HTTP 1.1

Unfortunately there is a problem with Flash on Mac OS X. It does not use the OS proxy settings and does not appear to offer any proxy settings of its own. Therefore when you run Flash movies in the authoring environment or stand-alone they do not use Charles.

However, if you run your Flash movie in a browser it will use the correct proxy settings and use Charles.

A possible workaround for this problem is to use the Reverse Proxy feature of Charles so that you can make the URL you connect to actually pass through Charles (eg. http://localhost:12345/).

If you see the following error message when you’re trying to use Charles:

Resource temporarily unavailable: recv failed
Try turning off “Parental Controls” on your account to allow Charles to run.

After recording for a while Charles will run low on available memory. To free up memory you should clear the current session.

If you frequently run out of memory you can increase the default heap size.

Windows

Edit C:Program FilesCharlesCharles.ini and change vm.heapsize.preferred to a higher number. Be sure not to remove any other the letters or symbols around the numbers!

Mac OS X

Find Charles.app in your Applications folder, right click and choose Show Package Contents. Open the Contents folder and open Info.plist in a text editor, such as Text Edit. Find VMOptions and change the number in -Xmx256m. Be sure not to remove any other the letters or symbols around the numbers!

Linux

Edit the charles.sh file and change the number in -Xmx256m. Be sure not to remove any other the letters or symbols around the numbers!

Try starting Charles before establishing the VPN connection. If you quit and relaunch Charles while the VPN is running, you may need to disconnect and reconnect the VPN again.

If you need to run multiple instances of Charles on a single Windows machine, such as in a Citrix environment, you need to make a few changes to how you use Charles.

In the Charles folder in Program Files, edit the Charles.ini file and remove the «single.instance=dde» line, then save the Charles.ini file.

Each user will need to configure Charles to use a different port. I suggest setting Charles to use a dynamic port.

If you need to run multiple instances of Charles as the same user you need to use a command-line option to direct Charles to use a different config file.

Charles shows a measure of the latency on each request on the Overview tab. Charles calculates latency by measuring the time taken between finishing sending the request and starting to receive the response. Therefore latency includes network latency and server latency, that is the time spent processing the request.

For static requests the server is usually able to respond instantly, unless under load, so the latency figure mostly represents the network latency.

For dynamic requests, or any request for which the server has to do some work, you can subtract an approximate network latency to determine how long the server spent processing the request.

The jug is part of the Charles folklore. It once belonged to a man named Charles, but Charles is not named after him.

This appears to be a fault in Mac OS X Lion, where it takes 5 seconds to resolve .local domain names, even if they are hardcoded in your /etc/hosts file. You can work around this problem by using Charles’s DNS Spoofing tool intead of /etc/hosts, however you’ll experience the .local DNS resolution delay when not using Charles. I recommend using an alternative TLD such as .dev.

Charles 3.4 changes the default behaviour of SSL in Charles to opt-in rather than opt-out. You must now opt-in each site you wish to enable for SSL proxying. This change was made to improve the behaviour of Charles. There are a number of applications running on computers that require SSL connections and get confused by the Charles SSL certificate used for SSL proxying. Also defaulting every site into SSL proxying could cause unwitting security problems for Charles users, such as if you Internet Banking site is proxied and your password visible in plain text inside Charles.

This change does mean that you now need to tell Charles about each SSL site you want to proxy, or you can opt in to proxy them all again.

To opt in a specific site, right-click on the host name in the tree view and turn on SSL Proxying. You may need to restart your browser to get it to close its existing non-SSL proxied connection. You can also control the list of SSL proxied hosts in the Proxy Settings dialog.

To opt in all sites, open the Proxy Settings dialog, go to the SSL tab, and enter a * into the list of locations.

These warnings will appear if you’re using Charles’s SSL Proxying feature. You can configure your browser (or other client application) to trust the SSL certificates that Charles generates, or you can just trust individual certificates (if the browser or application gives you that option).

Chrome by default rejects all localhost traffic if it has an invalid SSL certificate. This invalid certificate may be due to not trusting the Charles SSL certificate, or it may be because the SSL certificate your localhost server is using has expired or has the wrong name.

Check the connection, and your certificate, in another browser, as other browsers are not so stringent.

If this is the issue, we recommend fixing the issue with your certificate—such as renewing it or adding the correct common name to the certificate.

You can also change the setting in Chrome, so it no longer rejects these certificates outright. Do this by going to chrome://flags/#allow-insecure-localhost and enabling Allow invalid certificates for resources loaded from localhost.

Licensing

No problem! Please use the Lost License Key form to automatically receive a new email containing your key. If you still can’t recover your key please contact me using the Contact Form and place a Sales enquiry.

In order to deploy license keys during installation you need to copy a Charles preferences file into the appropriate location. Please configure a copy of Charles with the correct license key and then make a copy of the preferences file to use as the source file.

Please ensure that you have sufficient Charles licenses for your installation.

The Charles preferences file is found in different locations on each OS:

• Windows: %APPDATA%\Charles\charles.config
• Mac OS X:

To use Charles as your HTTP proxy on your iPhone you must manually configure the HTTP Proxy settings on your WiFi network in your iPhone’s Settings.

Go to the Settings app, tap Wi-Fi, find the network you are connected to and then tap the blue disclosure arrow to configure the network. Scroll down to the HTTP Proxy setting, tap Manual. Enter the IP address of your computer running Charles in the Server field, and the port Charles is running on in the Port field (usually 8888). Leave Authentication set to Off.

All of your web traffic from your iPhone will now be sent via Charles. You should see a prompt in Charles when you first make a connection from the iPhone, asking you to allow the traffic.

Remember to disable the HTTP Proxy in your Settings when you stop using Charles, otherwise you’ll get confusing network failures in your applications!

Simulator

As of Charles v3.9.3 there is an item in the Help menu, «Install Charles CA SSL Certificate in iOS Simulators», which will automatically install Charles’s SSL CA certificate in your iOS Simulators.

Alternatively, you can change your code so that NSURLConnection accepts any SSL certificate. Please see the question and answer on Stack Overflow: http://stackoverflow.com/questions/933331/how-to-use-nsurlconnection-to-connect-with-ssl-for-an-untrusted-cert

If you’re only browsing a single website in Safari you can just accept the certificate in Safari and that will work for that site. If the SSL site is only being used to load resources such as images, then you’ll need to visit it directly and accept the certificate before it will work.

Device

iOS 4 and later

On the device, set your HTTP proxy to use Charles, and then browse to http://www.charlesproxy.com/getssl to install the certificate.

SSL Pinning

Note that some apps implement SSL certificate pinning which means they specifically validate the root certificate. Because the app is itself verifying the root certificate it will not accept Charles’s certificate and will fail the connection. If you have successfully installed the Charles root SSL certificate and can browse SSL websites using SSL Proxying in Safari, but an app fails, then SSL Pinning is probably the issue.

After you’ve installed the root SSL certificate for your installation of Charles on your iOS device, you will be able to use SSL Proxying with apps. As of Charles 3.11.4 you can now do this with apps compiled and running on iOS 9 with App Transport Security.

Note that some apps implement SSL certificate pinning which means they specifically validate the root certificate, and will not work with Charles.

If you are on iOS 10.3 or later, there is an extra step required to trust Charles’s root SSL certificate. Open the Settings.app and navigate to General > About > Certificate Trust Settings, and find the Charles Proxy certificate, and switch it on to enable full trust for it (More information about this change in iOS 10).

In the event that you continue to have difficulties using SSL Proxying with your own apps, you could try disabling ATS. To disable ATS you need to add keys to your app’s Info.plist file, as below. See this tech note from Apple for more information.

You must remember to re-enable ATS before you release your app to take advantage of the security that ATS provides.

Troubleshooting

Outlook for Mac doesn’t play nicely with Charles. Add the hostname of your mail server to the Bypass Proxies text area in the Proxy Settings, Options tab. For example, «mail.example.com». This will configure your system to not use Charles as its proxy when connecting to your mail server.

Charles is developed by XK72. All content is copyright 2021. Site design by Matthew Buchanan.

Источник