.env to take over existing environment, which was used in previous versions < 3.0.40.\
3\. For version 3.4.0 the symlinks will point to new GSC endproints to ensure automatic migration to GSC endpoints (see chapter Version History and Greenbox Migration).
{% endhint %}
With installation of an additional activation package, the user can activate another environment to select another cloud gateway endpoint. Depending on the device type, Cloud Proxy uses a specified environment as default, if it was started for the first time without installed activation package.
{% hint style="info" %}
In addition, since versions 3.0.40 and 3.4.0 different CG and GSC endpoint are used as defaults. Please refer to documentation of corresponding Cloud Proxy version to get more details. Since version 3.5.0 (VOS3 support added), CG endpoints are no longer installed as default environments with the base package. Only versions >=3.0.50 can use it, which is available for VOS/VOS2 only.
{% endhint %}
The following activation packages are provided with this Cloud Proxy release:
| | | |
| ----------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Environment | Description | Activation package |
| **`gsc_dev`** | GSC Development Cloud | VOS/VOS2 platform:
dl.cloudproxy-cfg-gsc\_dev-X.X.X-X-prod.tar
(system package for productive and CpDev unit)
dl.cloudproxy-cfg-gsc\_dev-X.X.X-X.tar
(system package for OsDev unit)
VOS3 platform:
dl.cloudproxy-cfg-gsc\_dev-X.X.X-X.tar
(sys\_prx package for OsDev unit only. Requires new signing for other device types!)
Note
\[These download packages cannot be used for productive units, since the environment gateway has not installed productive AuthEX CA! If installed on a productive unit, Cloud Proxy will ignore this configuration and fallback to default environment gsc\_prod. ]{style="color:red"}
VOS/VOS2 platform:
dl.cloudproxy-cfg-gsc\_qat-X.X.X-X-prod.tar
(sys13 package for productive and CpDev unit)
dl.cloudproxy-cfg-gsc\_qat-X.X.X-X.tar
(sys13 package for OsDev unit)
VOS3 platform:
dl.cloudproxy-cfg-gsc\_qat-X.X.X-X.tar
(sys\_prx package for OsDev unit only. Requires new signing for other device types!)
Note
\[These download packages are allowed to be used for both, productive and test units!]{style="color:red"}
VOS/VOS2 platform:
dl.cloudproxy-cfg-gsc\_cst-X.X.X-X-prod.tar
(sys13 package for productive and CpDev unit)
dl.cloudproxy-cfg-gsc\_cst-X.X.X-X.tar
(sys13 package for OsDev unit)
VOS3 platform:
dl.cloudproxy-cfg-gsc\_cst-X.X.X-X.tar
(sys\_prx package for OsDev unit only. Requires new signing for other device types!)
Note
\[These download packages are allowed to be used for both, productive and test units!]{style="color:red"}
VOS/VOS2 platform:
dl.cloudproxy-cfg-gsc\_prod-X.X.X-X-prod.tar
(sys13 package for productive unit)
VOS3 platform:
dl.cloudproxy-cfg-gsc\_prod-X.X.X-X.tar
(sys\_prx package for OsDev unit only. Requires new signing for other device types!)
Note
\[These download packages are allowed to be used on productive units only! If installed on a test unit (CpDev or OsDev), Cloud Proxy will ignore this configuration and fallback to default environment gsc\_dev.]{style="color:red"}
VOS/VOS2 platform:
dl.cloudproxy-cfg-gsc\_cst\_us-X.X.X-X-prod.tar
(sys13 package for productive and CpDev unit)
dl.cloudproxy-cfg-gsc\_cst\_us-X.X.X-X.tar
(sys13 package for OsDev unit)
VOS3 platform:
dl.cloudproxy-cfg-gsc\_cst\_us-X.X.X-X.tar
(sys\_prx package for OsDev unit only. Requires new signing for other device types!)
Note
\[These download packages are allowed to be used for both, productive and test units!]{style="color:red"}
VOS/VOS2 platform:
dl.cloudproxy-cfg-gsc\_prod\_us-X.X.X-X-prod.tar
(sys13 package for productive unit)
VOS3 platform:
dl.cloudproxy-cfg-gsc\_prod\_us-X.X.X-X.tar
(sys\_prx package for OsDev unit only. Requires new signing for other device types!)
Note
\[These download packages are allowed to be used on productive units only! If installed on a test unit (CpDev or OsDev), Cloud Proxy will ignore this configuration and fallback to default environment gsc\_dev.]{style="color:red"}
Environment configuration file as specified in chapter Environment Configuration File.
Note
Flag activate in section cloud in the configuration file can be used to activate the environment with the next startup of Cloud Proxy (after the User Configuration Package is installed).
The filename \.env must differ to default environment files as installed with the Cloud Proxy base package (see chapter Default environments and activation). If a name conflicts, the environment file \.env of the User Configuration Package is ignored.
|
| `/etc/config/proxy` | `*.pem, *.p12` | Additional certificates/key files, which are referred by the environment file `.env`. For more details refer to descritiption of `ca-file` and `client-id` in chapter [Environment Configuration File](#sec_prx_environment_configuration). |
{% hint style="info" %}
For more details how to create such an User [Config](/adk-5.0-programmers-guide/readme/annotated/class_config.md) Package, please refer to user guide Verifone Secure Installer ERS.
{% endhint %}
#### VOS3 User Configuration Packages
Cloud Proxy user configuration is read-only and shall be installed with user previleges (signer `SPONSOR`). VOS3 system typically installs read-only user files with package type `user_ro`, which means that the files will be placed to home directory for user `usr1`-`usr16`:
```fragment
/home/usr
```
Since other application files are located there, User configuration Packages for Cloud Proxy must use subfolder `proxy` to separate them from application:
```fragment
/home/usr/proxy
```
Additional group permissions must be set for the package so that Cloud Proxy is able to access and lookup the files.
At startup Cloud Proxy checks for the existence of the folder with included files starting from `usr1` up to `usr16`. If there are related files found under a specific user, this user directory is applied as source for user configuration files. This means, the first user providing the files wins, other users with higher user numbers will be ignored.
User Configuration Packages may contain the following data:
1. Bundle with arbitrary name (user: `usr1-usr16`):
* Package with arbitrary name (user: `usr1-usr16`, group: `usr1sys`, type: `user_ro`):
| | | |
| -------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Destination | File | Description |
| `/home/usr/proxy` | `.env` | Same as for VOS/VOS2 platform, for description please refer to chapter [VOS/VOS2 User Configuration Packages](#subsubsec_prx_user_config_vos_vos2) above. |
| `/home/usr/proxy` | `*.pem, *.p12` | Same as for VOS/VOS2 platform, for description please refer to chapter [VOS/VOS2 User Configuration Packages](#subsubsec_prx_user_config_vos_vos2) above. |
A sample User Configuration Package for the corresponding platform comes along in subfolder `example/load/usr_config` of documentation package `prx-doc-X.X.X-X.zip`:
* **dl.prx-usrconfig-sample-env-X.X.X-X.tar** This package installs a sample environment file `sample.env` with a root CA certificate `mycloud-ca.pem`. The certificate is refered by `ca-file` in the environment file, which is used to autenticate the server for cloud endpoint `url`.
* **dl.prx-usrconfig-old-cg-envs-X.X.X-X.tar** This package installs old CG environments (`dev`, `test`, `staging1` and `prod`) for `verifone.cgateway.com`. Please note that these environments are \[deprecated]{style="color:red"} and shouldn't longer be used productive environments. Users should migrate to the new GSC environments soon, since old CG environment endpoints will go offline sooner or later. For more details please refer to chapter [Version History and Greenbox Migration](#sec_prx_versions_greenbox).
## Environment Configuration File
This chapter describes the content and settings of an environment configuration file. Several default environments come along with installation of Cloud Proxy base package (see chapter [Cloud Proxy base packages](#subsec_prx_base_packages)), which can be activated with additional packages installed on top of the base installation. In addition, users have the option to install additional environments with a User Configuration Package (see chapter [Install additional environments](#subsec_prx_install_additional_environments)).
The configuration file for the active environment is read at startup of Cloud Proxy and contains the following settings:
(Example configuration file: `gsc_qat` environment in file `test.env`)
```fragment
[cloud]
; URL of the VFI-Cloud environment, e.g. vfi-cloud.verifone.com:8843, URL is mandatory, default port: 8843
url=qat2.test-gsc.vfims.com:443
; name of the environment (alias). This is used as 'environment name' with the Cloud Proxy Configuration Interface
; (see parameters cloud_env_list and cloud_env_list2). If not set, the environment filename is used without
; extension *.env. Please note that alias must be identical crossover environment configuration files and also not
; conflict with other environment filenames, if these files don't use an alias.
alias=gsc_qat
; productive environment, set to value 'true', if this environment uses productive AuthEx CA, which can be used by productive units only.
; Value 'false' implies that only cp-dev and os-dev devices can use this environment having DEV AuthEx CA (default: false).
; Please note variable 'allow_prod_unit', which allows productive units to use non-prod environment with AuthEx!
prod=false
allow_prod_unit=true
; activate this environment after it is installed with user config package, default: false
; activate=false -> default configuration coming along with Cloud Proxy base package
; name of the file containing the root CA certificate of VFI cloud, default=cloud-ca.pem
; Note: In case of using 'new-ca-file', 'ca-file' contains 2 CA root certificates, which
; are used during transition phase to migrate VFI cloud to a new CA (CA update):
; 1. CA certificate: for VFI cloud with the current CA to be replaced (before the CA update)
; 2. CA certificate: for VFI cloud with the new CA (after the CA update)
ca-file=cloud-ca.pem
; name of the file containing the new root CA certificate of VFI cloud after a pending
; CA update, default=empty
; Note: This certificate must equal the new 2. CA certificate specified in file 'ca-file',
; since Cloud Proxy switches from 'ca-file' to 'new-ca-file', after it has connected
; to the updated VFI cloud for the first time. From this point, Cloud Proxy will not
; be able to connect to VFI cloud using the old CA.
; new-ca-file=new-cloud-ca.pem
[proxy]
; filename of the PEM or PKCS12 file containing an alternative client certificate/private key.
; This is used, if device hasn't installed AuthEx certificate/key or AuthEx was disabled Cloud Proxy Configuration Interface.
; default: empty (force usage of AuthEx certifcate/key if installed)
; client-id=
; label string used by cloudproxy for the client certificate (if empty 'client-id' w/o file extension is used)
; client-id-label=
; client timeout in sec when waiting for replies from the cloud, default=30sec
timeout=30
; listen port number for incoming connections from the clients, default=8888
port=8888
[logservice]
; URL of the log gateway (usually a relative path)
url=/cp
; host as destination for the logs (host used for routing the logs)
host=logging-service.verifone.com
; initial log level used for CP app logging, default=5
loglevel=7
[connectivity]
; URL of the availability service (usually a relative path)
url=/DeviceConnectivity/Check
; availability service host
host=gsc
```
Description of settings in configuration file `.env`:
\[TABLE]
## Local HTTP Proxy Support
Since version 3.4.0 (and version 3.0.40), Cloud Proxy has added support to establish Cloud connections over a HTTP proxy. This HTTP proxy usually is available in LAN and provides HTTP clients access to outer world. Instead of connecting to Cloud endpoint directly (which is specified by [Environment Configuration File](#sec_prx_environment_configuration)), Cloud Proxy first establishes the TCP/IP connection to this local HTTP proxy. As second step it sends a HTTP CONNECT request to this proxy to establish a transparent TCP/IP channel to the Cloud endpoint. Finally, Cloud Proxy does the TLS handshake over this spliced channel to establish a secure end-to-end TLS connection to the Cloud endpoint.
The activation of a local HTTP proxy is done by configuration file `httpproxy.cfg`. The file may contain multiple sections to configure a HTTP proxy for one or more specific Cloud environments.
```fragment
; productive environment gsc_prod uses this proxy (specified by prod.env)
[gsc_prod]
proxy=192.168.188.250:8888
attribute_1=Proxy-Authorization: Basic YW5kcmU6ZHJvd3NzYXA=
attribute_2=X-VFI-TEST: Some proxy data
attribute_3=X-VFI-TEST2: More proxy data
; pseudo environment name 'default' is used to configure a default HTTP proxy
[default]
proxy=192.168.188.250:8080
attribute_1=X-VFI-TEST: Some proxy data
attribute_2=X-VFI-TEST2: More proxy data
```
The section name represents the environment name, which is either the environment alias specified in (see [Environment Configuration File](#sec_prx_environment_configuration)) or the basename of environment configuration file w/o extension, in case no alias is used.
{% hint style="info" %}
Default environment configurations provided with Cloud Proxy base package use aliases, which are listed in table of chapter [Default environments and activation](#subsec_prx_default_environments) as environment name. Thus, user must specify the section by these names to match an environment, e.g. `gsc_prod` is used for environment file `gsc-prod.env`.
{% endhint %}
Pseudo environment name `default` represents the default HTTP proxy, which is used, if the name of the active environment does not match any other section. Section `default` can be used as one and only section, if only one proxy shall be used for all environments. If section `default` is omitted and no corresponding section matches to the name of the active environment, no local HTTP proxy will be used.
{% hint style="info" %}
If additional environments are installed by User Configuration Package (see chapter [Install additional environments](#subsec_prx_install_additional_environments)), users should avoid to use `default` as environment name. In this case section `default` would be applied for this environment only.
{% endhint %}
Description of section parameters in configuration file `httproxy.cfg`:
| | |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Parameter | Description |
| `proxy` | URL of the HTTP proxy, which specifies a host name or IP address (with a port). Both parameters are separated by ':'. If no port is specified, port 8888 is used as default.
Note
Please note that parameter proxy is mandatory and section skipped, if it misses mandatory data or contains an invalid format.
IPv6 IP address are bracketed with \[], example: proxy=\[::1]:12345.
HTTP header attribute(s) added to HTTP CONNECT request, which is sent to HTTP proxy to establish the TCP/IP channel. Attribute \ starts with 1, numbers of following attributes must have ascending order.
Note
Attributes for HTTP CONNECT might be required, if the HTTP proxy requires authentication with Proxy-Authorization.
Please note that Cloud Proxy binary depends on ADK libraries libvfiipc and liblog. Instructions for installation on the corresponding platform can be found in documentations of ADKIPC and ADKLOG projects.
AuthEx key/certificate for SSL client authentication is installed and supported by the system:
1=supported
0=unsupported
|
| `proxy` | `buildinfo` | Build information string of format:
\ \ \ \ \ \:\:\
|
| `proxy` | `device_type` | Detected device type string:
prod=productive unit
os-dev=Fusion/Engage OsDev unit
cp-dev=Fusion/Engage CpDev unit
|
| `proxy` | `version` | Version string in format:
\.\.\-\
|
| `proxy` | `result` | Result:
success=command successful
error=command failed
|
Example:
```cpp
{
"proxy" : {
"auth_ex_support" : 0,
"buildinfo" : "cloudproxy 3.0.0-1 Mar 14 2018 12:16:56",
"device_type" : "prod",
"version" : "3.0.0-1",
"result" : "success"
}
}
```
### Read Configuration
Configuration settings can be read with command `readconfig`.
`CloudProxyConf` parameters:
| | | |
| --------- | --------- | ------------ |
| Container | Parameter | Content |
| `proxy` | `command` | `readconfig` |
Example:
```cpp
{
"proxy" : {
"command" : "readconfig"
}
}
```
`CloudProxyConfResponse` parameters:
\[TABLE]
Example:
```cpp
{
"proxy" : {
"auth_ex" : 1,
"cloud_env" : "dev",
"cloud_env_file" : "proxy/dev.env",
"cloud_env_list" : ["prod", "dev", "test", "staging1"],
"cloud_env_list2" : [
{"name":"prod",
"prod":true,
"certs":["auth-ex"]
},
{"name":"dev",
"prod":false,
"certs":["auth-ex"]
},
{"name":"test",
"prod":false,
"certs":["auth-ex"]
},
{"name":"staging1",
"prod":false,
"certs":["auth-ex"]
}
],
"cloud_hostname" : "dev.cgateway.verifone.com",
"result" : "success"
}
}
```
### Write Configuration
Configuration settings can be written with command `writeconfig`.
`CloudProxyConf` parameters:
| | | |
| --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Container | Parameter | Content |
| `proxy` | `command` | `writeconfig` |
| `proxy` | `cloud_env` | Name of cloud environment to be enabled, a string of environment list provided with parameter cloud\_env\_list in command readconfig (see above).
Note
Test units (CpDev and OsDev) does not allow to enable environment prod and in this case command writeconfig will fail on these devices.
If installed and supported, AuthEx certificate for SSL client authentication can be enabled or disabled:
1=enable
0=disable
Note
It is not allowed to disable AuthEx certificate for an environment, which does not provide an alternative certificate in certificate list different than string auth-ex (see parameter certs in environment list cloud\_env\_list2).
In addition, AuthEx certificate cannot be enabled, if it is not installed or supported by the system (see chapters Read Static Information and Read Configuration).
In both cases command writeconfig will fail.
Result:
success=command successful
error=command failed
|
Example:
```cpp
{
"proxy" : {
"result" : "success"
}
}
```
### Cloud Connectivity Check
Applications can use command `cloudcheck` to check the connectivity to VFI Cloud gateway. With this command Cloud Proxy will establish a secure SSL connection to VFI Cloud gateway, which will forward the request to *Verifone Connectivity Service* webserver, which is behind the VFI Cloud gateway. URL and host of the *Verifone Connectivity Service* webserver is configured in environment configuration file `.env` (see chapter [Environment Configuration File](#sec_prx_environment_configuration)).
`CloudProxyConf` parameters:
| | | |
| --------- | --------- | ------------ |
| Container | Parameter | Content |
| `proxy` | `command` | `cloudcheck` |
Example:
```cpp
{
"proxy" : {
"command" : "cloudcheck"
}
}
```
`CloudProxyConfResponse` parameters:
| | | |
| --------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Container | Parameter | Content |
| `proxy` | `error_code` | HTTP status code of Connectivity Check request, examples:
200 (OK)
503 (Service Unavailable)
Note
Status codes 2xx are returned for success, others mean failure.
Result as string (readable error reason), examples:
OK
Service Unavailable
|
| `proxy` | `result` | Result:
success=command successful
error=command failed
Note
success is returned for HTTP status code 2xx, else error is returned