Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt

Use this file to discover all available pages before exploring further.

Note: You must have the necessary privileges to your Google Cloud account to perform maintenance operations.

​
View the logs

To view the Co-Signer’s logs, go to the GCP’s VM instances page and validate that you see the right project (for example, “GCP-Customer-Cosigner-Dev”). After that, click on the relevant VM name and then press “logging” (which appears under “Logs”). This will open a new window with the customer Co-signer’s logs.

​
Observe the status

To check the Co-signer’s health, run the following command: 
gcloud compute instances describe <vm-name> --zone=<vm-zone> | grep status
Search for the status field of the VM in the output and confirm it is set to RUNNING. However, this does not guarantee the health of the Co-signer. To verify its functionality, monitor the transaction activity passing through it. Also, use the Co-signers management tab to observe the online / offline status.

​
List the paired API users

Use the Co-signers management tab to observe the paired API users.

​
Retrieve the public key

You can view the Co-signer’s logs in Google Cloud’s console to find the public key used by the Callback Handler’s server for JWT-encoded signed message authentication. Search for public key in the logs, as shown in the example below.

​
Stop the Co-signer

You can stop the Co-signer by running: 
gcloud compute instances stop <vm-name> --zone=<vm-zone>
Note: This operation will not delete the VM.
You can also stop the VM from the GCP console.

​
Restart the Co-Signer

In case the Co-signer’s VM is down, given the Co-signer was already created, you can restart the Co-signer by running: 
gcloud compute instances start <vm-name> --zone=<vm-zone>
When you restart the Co-signer after installing it, it will use the same configuration (metadata), so you don’t need to enter all the parameters again.

​
Retrieve the running version

Use Google Cloud’s console to check the Co-signer’s running image version by observing the tee-image-reference field in Custom metadata in the Details section. Alternatively, you can search for Initializing CustomerCosignerGCPConfidentialSpace, commit sha within the instance logs.

​
Update proxy settings

You can update or remove proxy settings on a running Co-signer without performing a full upgrade. The --update-proxy flag on the install/upgrade script handles this. It updates the VM’s instance metadata in place and resets the VM to apply the change. No new VM is created. The operation causes approximately 2 minutes of downtime while the VM restarts.

​
Run the update

./client_install_upgrade_api_cosigner_script.sh --update-proxy cloud-resources-<timestamp>.yaml
Replace cloud-resources-<timestamp>.yaml with the resources file generated during your installation.

​
What the script does

  1. Loads your current configuration from the resources YAML file and displays a summary, including whether a proxy is currently configured.
  2. Prompts you for the new proxy URL. To remove an existing proxy, press Enter without entering a value.
  3. If a proxy URL is provided, encrypts it using your Cloud KMS key (credentials are never stored in plaintext), then prompts for NO_PROXY patterns. The current NO_PROXY value is shown as the default; press Enter to keep it.
  4. Displays a summary of the changes and asks for confirmation before touching the running VM.
  5. Updates the VM’s instance metadata with the new configuration and resets the VM.
  6. Writes the updated proxy settings to your resources YAML file.

​
Proxy URL format

http://proxy.example.com:8080
To authenticate to the proxy, include credentials in the URL: 
http://username:password@proxy.example.com:8080

​
Effect on WebSocket vs. long-polling

When a proxy is configured, the Co-signer uses long-polling (REST) for communication with Fireblocks. WebSocket connections cannot reliably traverse proxies. When you remove a proxy, the Co-signer reverts to the WebSocket setting that was active before the proxy was added.

​
Verify the update

Once the VM is back online (approximately 2 minutes after the reset), proxy activity appears in Cloud Logging. To stream recent logs: 
gcloud logging read 'resource.type=gce_instance AND labels.instance_name=YOUR_VM_NAME' \
  --limit=50 \
  --order=desc
Replace YOUR_VM_NAME with your Co-signer VM name (visible in the summary the script prints before confirmation).

​
Update the Co-signer

You can update the Co-signer by running the following script: 
client_stop_and_update_gcp_api_cosigner_script.sh
This script performs the following:
  • Stops the existing VM running the current Co-signer.
  • Updates the OIDC workload identity pool provider’s attestation verification with the new image’s SHA of the new version.
  • Create a new VM that runs the new image.
The new Co-Signer VM utilizes the same database, keys, and cloud resources as the previous one.
Important notes:
  • Delete the old VM once the new one is fully operational. Because the policy is configured to protect the VM from deletion, use the GCP console to disable the deletion protection under VM > Edit > UNtag "Enable deletion protection" and save the new settings before deleting the VM.
  • If a proxy was configured when the Co-signer was installed, the upgrade carries that configuration forward automatically. No additional input is required. To change or remove proxy settings on a running Co-signer, use the --update-proxy flag instead of performing an upgrade. See the Update proxy settings section.
  • Please make sure to refer this doc to get the Image SHA number.

​
Migrate to a new machine

Stop the current Co-signer VM and set up a new one using the same resources besides the VM.

​
Configure the communication protocol

WebSocket is the default protocol the Co-signer uses to communicate with the Fireblocks SaaS. You can switch to HTTP Long Polling by configuring the client_install_gcp_api_cosigner_script.sh script. To configure the Co-signer to use HTTP long polling, you can create a new VM that will use the same resources, but ensure you remove the \"--websocket\" parameter from the create_vm_cmd line so that it will look like this: 
--metadata
^~^tee-image-reference=$image_ref~tee-container-log-redirect=true~tee-cmd='[\"--initial-config\", \"$initial_config\", \"$bucket\", \"$key_path\"]'"
Instead of: 
--metadata
^~^tee-image-reference=$image_ref~tee-container-log-redirect=true~tee-cmd='[\"--initial-config\", \"$initial_config\", \"$bucket\", \"$key_path\",\"--websocket\"]'"
If you don’t want to create a new VM, you can edit the VM’s metadata and instruct it to restart in HTTP Long Polling.
  • Stop the Co-signer0 VM
  • From the GCP console, locate VM > Edit > Metadata
  • Remove “--websocket” from the “Value 1” matching Key 1 which is “tee-cmd”
  • Click Save and restart the VM to apply the changes to the Co-signer