Configuring & Troubleshooting Proxy for Ballerina Development Environment
Corporate networks often restrict direct HTTP access and mandate the use of proxies for a variety of purposes such as content filtering, security, caching, and monitoring. In this context, configuring Ballerina Swan Lake to operate via a proxy becomes essential for working within such environments to publish packages to Ballerina Central and to use packages from it.
Depending on organizational requirements, It might need to set up a proxy directly for the Ballerina client, known as a forward proxy. In other cases, a transparent proxy would be beneficial, which works in the background without needing any manual setup from the user.
Configuring a forward proxy
A forward proxy necessitates explicit proxy configuration within the Settings.toml file found in the BALLERINA_HOME directory, typically located ~/.ballerina on Linux systems and C:/Users/<user_name> on Windows platforms. Configuring the proxy involves specifying the host, port, and credentials. This configuration can be achieved within the Settings.toml file by either supplying these parameters — host, port, and credentials. The inclusion of credentials is requisite solely in instances where the proxy mandates authentication. You can refer to the following example.
[proxy]
host = "127.0.0.1" # IP address/ hostname of the proxy
port = 8080 # proxy portor
[proxy]
host = "127.0.0.1" # IP address/ hostname of the proxy
port = 8080 # proxy port
username = "luhee"
password = "1234"Configuring a transparent proxy
Transparent proxies operate by intercepting network traffic without necessitating any client-side configuration. Clients remain unaware of the presence of the transparent proxy. This type of proxy intercepts traffic at the network level, commonly employing methods such as port redirection or NAT (Network Address Translation). Therefore, no explicit configuration in the Settings.toml file is required to utilize a transparent proxy. You can simply build your packages or pull library packages from the central repository without any additional configuration steps.
Troubleshooting
Occasionally, users may encounter issues similar to the ones below when attempting to connect via the proxy:
1) package not found:<org/package-name> error although the package is there in the central.
2) PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested targeterror.
These issues often arise when encountering SSL/TLS certificate validation problems during HTTPS connection. Specifically, the proxy server’s SSL/TLS certificate might not be trusted by the Java Runtime Environment (JRE), which is utilized by Ballerina, leading to connection issues. To resolve this, you may need to import the proxy server’s Certificate Authority (CA) certificates into the JRE’s truststore. Follow the steps outlined below to import the CA certificates:
- Identify the CA certificates associated with the proxy server.
These certificates are typically provided by the proxy administrator or can be obtained from the proxy server’s documentation. If you are browsing through the same proxy, you can potentially obtain the necessary certificates via your web browser. Below, I’ll outline the steps to demonstrate this process using Firefox.
- Access a URL (e.g., google.com) and locate the lock icon in the address bar. Then, choose “Connection secure.”
- Proceed to the “More information” section.
- Navigate to the “Security tab” and select the “View Certificate” button.
- At this juncture, you’ll encounter a series of tabs; pinpoint the one pertaining to the proxy. Within the “Miscellaneous” category, you can download the proxy certificate.
2. Head to the Ballerina installation directory and locate the Java Runtime Environment (JRE).
Depending on the operating system, the Ballerina installation directory may vary. For Unix-based systems, you can utilize the which bal command, while for Windows, you can use the where bal command. Below, I’ll illustrate using macOS.
In some Unix-based systems such as Linux distributions, using the which bal command may only provide the binary path of the Ballerina executable without revealing the exact installation directory. In such cases, alternative commands can be employed to ascertain the actual installation directory. You can utilize the following approach:
Execute the following command in your terminal:
dirname $(dirname $(readlink -f $(which bal)))This command retrieves the symbolic link of the bal executable, resolves its absolute path, and then extracts the directory two levels up to determine the Ballerina installation directory.
Next, navigate to the directory /Library/Ballerina. Within this directory, you’ll encounter several folders, including the dependencies folder. Inside the dependencies folder, you’ll discover all the Java Runtime Environments (JREs) packaged with the Ballerina distribution.
3. Add necessary certificates to JRE’s truststore.
Use the keytool utility provided by JRE to import the CA certificates into the truststore. You can do this by executing the following command in your terminal or command prompt with administrative privileges:
<BALLERINA_JRE>/bin/keytool -import -trustcacerts -file <CERTS_PATH> -alias <ALIAS_NAME> -keystore <BALLERINA_JRE>/lib/security/cacertsReplace <BALLERINA_JRE> with the JRE location, <ALIAS_NAME> with a suitable alias for the certificate, <CERTS_PATH> with the file path to the CA certificate.
You may be prompted to enter the truststore password. The default password for JRE’s truststore is changeit unless it has been modified.
Upon successful activation, expect an output similar to the following:
luheerathan:jdk-17.0.7+7-jre root# ./bin/keytool -import -trustcacerts -file /Users/luheerathan/.mitmproxy/mitmproxy-ca-cert.pem -alias mitmproxycert -keystore ./lib/security/cacerts
Warning: use -cacerts option to access cacerts keystore
Enter keystore password:
Owner: O=mitmproxy, CN=mitmproxy
Issuer: O=mitmproxy, CN=mitmproxy
Serial number: 3f73ad69d5b6d4fd5f83e2948b1905657232a64f
Valid from: Sun May 21 21:15:14 IST 2023 until: Fri May 20 21:15:14 IST 2033
Certificate fingerprints:
SHA1: E7:FC:39:3D:F4:EF:4E:AD:F2:C1:0B:EF:88:2C:11:A4:A5:76:43:02
SHA256: EC:27:DD:57:BC:D5:86:E2:4F:EE:F1:35:29:6E:D2:A1:4C:01:64:96:C6:4D:E6:C9:71:62:C7:8B:24:2B:F8:33
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen: no limit
]
#2: ObjectId: 2.5.29.37 Criticality=false
ExtendedKeyUsages [
serverAuth
]
#3: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
Key_CertSign
Crl_Sign
]
#4: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 73 07 4E 25 CE AE 6A 04 EB 53 13 1E 74 A1 F2 21 s.N%..j..S..t..!
0010: D9 56 33 3C .V3<
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
luheerathan:jdk-17.0.7+7-jre root# Certificate was added to keystore message confirms that the certificate has been successfully imported into the JRE’s truststore and is now available for use in establishing secure connections
It is advisable to adhere to the same approach for all Java Runtime Environments (JREs) located in the dependencies folder. This ensures consistent proxy configuration across different Ballerina versions, allowing seamless transitions without encountering proxy-related issues.
In scenarios where Ballerina is obtained as a zip artifact and Java is installed externally, it becomes necessary to add the certificates to the truststore of the Java installation. This can be achieved by following the previously outlined steps for importing certificates into the JRE’s truststore.
Once you follow these steps, you should be able to use a proxy for dependency management.
Feel free to contact us for further queries
References
