# Update regarding CVE-2026-65400
Source: https://docs.macstadium.com/CVE-2026-65400
## What you need to know
On August 6, Apple released emergency security updates for a critical vulnerability in macOS Screen Sharing, tracked as CVE-2026-65400. The flaw allows an attacker with network access to a Mac with Screen Sharing enabled to gain access without valid credentials. Apple’s advisory is available here: **[https://support.apple.com/en-us/148170](https://support.apple.com/en-us/148170).**
Because Screen Sharing is a standard access method for MacStadium-hosted Macs, we have taken a protective step on behalf of all customers: **inbound traffic to TCP port 5900 (the default Screen Sharing port) is now blocked at the MacStadium network edge.** This immediately removes the attack surface for every hosted Mac, patched or not.
**If your Mac was running an affected version and Screen Sharing was reachable from an untrusted network before the port was blocked, we recommend rebuilding the Mac from a known-good state rather than assuming it was not compromised.**
If Screen Sharing was never enabled, was only accessible through a private network or VPN, or your Mac was already patched, your exposure is substantially different. In those cases, patching macOS is the primary remediation.
> **Do not expose Screen Sharing directly to the Internet on an alternate port as a workaround.** If you need Screen Sharing access from an untrusted network, use an SSH tunnel or VPN/private network instead.
## What MacStadium has done
MacStadium has blocked inbound **TCP port 5900** at the network edge for hosted Macs.
This provides an additional layer of protection while customers patch or rebuild their systems.
SSH remains available and is unaffected by this vulnerability and the port block.
## Do I need to rebuild my Mac?
Use the following guidance:
| Scenario | Recommended action |
| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| Screen Sharing was never enabled | Patch macOS |
| Screen Sharing was only accessible through a private network or VPN | Patch macOS; rebuilding is generally unnecessary |
| Screen Sharing was reachable from the public Internet while the Mac was running an affected version | **Contact support and rebuild** |
| You are unsure whether Screen Sharing was publicly reachable | **Treat the Mac as potentially exposed and contact MacStadium Support for a rebuild** |
| You have evidence of unauthorized access | **Rotate credentials/secrets, contact support, and rebuild.** |
The network block prevents further access through TCP 5900, but **it does not establish whether a Mac was accessed before the block was implemented.**
## Recommended remediation: Wipe and rebuild the Mac
If your Mac was potentially exposed while running an affected version, the safest approach is to rebuild it from a known-good state.
#### Step 1. Back up required data: Back up the files you need to retain before requesting the rebuild. For example:
```text theme={null}
scp username@remote_host:/path/to/remote/file.txt /path/to/local/destination/
```
*Do not restore the entire system from a potentially compromised Mac.* Avoid restoring system files, applications, launch agents, scripts, or other executable/configuration content unless you have verified it is trusted.
#### Step 2. Open a MacStadium Support ticket
Ask MacStadium Support to wipe and reinstall the machine.
Support can help with the rebuild and getting the Mac back into service.
## Alternative: Self-service patching
If you have high confidence that your Mac was **not exposed or accessed before the network block**, you can patch the Mac yourself.
This option is appropriate, for example, if:
* Screen Sharing was never publicly reachable;
* the Mac was protected by a firewall or VPN;
* the Mac was already patched; or
* you have another reliable reason to establish that the vulnerable service was not exposed.
If you are uncertain, we recommend rebuilding instead.
#### Before you start
You will need:
* Your Mac's IP address or hostname
* Your administrator username and password
* An SSH client
#### Step 1: Connect over SSH
From a terminal on your local machine:
```text theme={null}
ssh youradminuser@your.server.ip.address
```
#### Step 2: Update macOS
First, check your current version:
```text theme={null}
sw_vers
```
Apple has released fixes for the following versions:
* **macOS Tahoe 26.6.1**
* **macOS Sequoia 15.7.9**
* **macOS Sonoma 14.8.9**
If you are already running one of these versions, no OS update is required.
List available updates:
```text theme={null}
softwareupdate --list
```
Find the appropriate update in the output and install it. For example:
```text theme={null}
sudo softwareupdate --install "macOS Tahoe 26.6.1-25G76" --restart --agree-to-license --user youradminuser --stdinpass
```
Enter your password when prompted.
The Mac will download and install the update and then reboot. Your SSH session will disconnect when the reboot begins.
Once the machine is back up, reconnect over SSH and confirm the version:
```text theme={null}
sw_vers
```
You should see a patched version such as 26.6.1, 15.7.9, or 14.8.9.
### Running macOS Ventura or older?
Apple has not released a patch for those versions.
Open a MacStadium Support ticket for assistance upgrading to a supported macOS version.
## Restoring Screen Sharing access
After patching, **we recommend keeping Screen Sharing inaccessible from the public Internet.**
There are two preferred approaches.
#### Option 1: Use an SSH tunnel
SSH tunneling allows you to use Screen Sharing without exposing the Screen Sharing service to the Internet.
First, make sure Screen Sharing is enabled on the Mac.
Then, from your local computer, create an SSH tunnel:
```text theme={null}
ssh -L 45900:127.0.0.1:5900 youradminuser@your.server.ip.address
```
Leave this SSH session open.
Then connect your VNC client to:
```text theme={null}
vnc://localhost:45900
```
The Screen Sharing traffic is carried through the encrypted SSH connection, while port 5900 remains inaccessible from the Internet.
#### Option 2: Use a private network or VPN
Customers using a MacStadium firewall, VPN, or other private connectivity can continue to use Screen Sharing over that private connection.
This is the preferred approach for customers who need persistent remote Screen Sharing access.
Restrict Screen Sharing so that it is accessible only from trusted networks whenever possible.
## What we do not recommend
**Do not expose Screen Sharing directly to the Internet simply by moving it to another port.**
Changing TCP 5900 to another port can reduce exposure to unsophisticated scanners, but it is not a meaningful security control. An attacker can discover services running on non-standard ports.
For this reason, MacStadium does **not** recommend configuring Screen Sharing to listen on an alternate publicly accessible port as a remediation for CVE-2026-65400.
Use an SSH tunnel, VPN, firewall, or other private-network control instead.
## Frequently asked questions
#### Does blocking port 5900 fix the vulnerability?
Blocking TCP 5900 prevents the known network attack path through the default Screen Sharing port. However, it does not patch macOS and does not determine whether a Mac was accessed before the block.
You should still install Apple's security update.
#### Do I need to rebuild every Mac?
No. Rebuilding is primarily recommended for Macs that may have been exposed to an untrusted network while running an affected version.
If Screen Sharing was never enabled, was protected by a private network or VPN, or the Mac was already patched, patching macOS is generally the appropriate remediation.
#### Can I continue using SSH?
Yes. SSH is unaffected by CVE-2026-65400 and remains available.
#### Can I use Screen Sharing after patching?
Yes. We recommend accessing it through a private network, VPN, or SSH tunnel rather than exposing Screen Sharing directly to the Internet.
#### What if I am running macOS Ventura or older?
Apple has not released a fix for those versions. Contact MacStadium Support for assistance upgrading to a supported macOS version.
# AWS-to-MacStadium VPN networking setup
Source: https://docs.macstadium.com/iaas/aws/aws-networking-setup
Configure an IPsec site-to-site VPN between Amazon VPC and MacStadium. Covers customer gateway, virtual private gateway, VPN connection, and traffic rules.
To establish a stable, persistent connection between Amazon Virtual Private Cloud (Amazon VPC) and your MacStadium private cloud, you need to configure an IPsec site-to-site VPN between the two clouds.
Currently, Amazon lets you create a site-to-site VPN where at all times one tunnel is active (up) and one is passive (down). A monitoring service checks frequently if the active tunnel is up and, if not, brings the passive tunnel up instead. This ensures minimal downtime.
Routing from Amazon to MacStadium is static.
To create a site-to-site VPN from your Amazon VPC to your MacStadium private cloud, you need to go through the following high-level steps:
1. Log in to your VPC service
2. Create a customer gateway
3. Set up a virtual private gateway
4. Create the site-to-site VPN connection
5. Ensure that AWS allows inbound traffic
## Log in to your VPC service
1. Log in to your AWS Management Console and access your VPC service.
2. In the top right corner of the screen, make sure that you're working in the correct region.
## Create a customer gateway
In Amazon, the customer gateway represents the MacStadium endpoint of the site-to-site VPN connection. When you configure the customer gateway, you need to use the networking information for your public network. By default, this is the FW1-Outside network. You can find the networking information for this network in Appendix B of your [IP Plan](/macstadium/macstadium-overview/ip-plan).
For more information about the customer gateway, see [Amazon VPC Documentation: Components of Your Site-to-Site VPN](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPC_VPN.html#VPN).
1. In the VPC service sidebar, locate the Virtual Private Network menu and select Customer Gateways.\\
![AWS VPC sidebar with Customer Gateways option highlighted]()
2. Click Create Customer Gateway.\\
![AWS Create Customer Gateway form with routing and IP address fields]()
3. Provide a Name.
* Set a name that helps you identify the gateway easily.
4. Select Static routing.
5. In the IP Address text box, provide the IP address of the public network listed in Appendix B of the IP Plan.
* By default, this is the FW1-Outside network.
6. Click Create Customer Gateway.
## Set up a virtual private gateway
In Amazon, the virtual private gateway represents the Amazon endpoint of the site-to-site VPN connection.
![AWS Virtual Private Gateways dashboard with gateway listed]()
For more information about the virtual private gateway, see [Amazon VPC Documentation: Components of Your Site-to-Site VPN](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPC_VPN.html#VPN).
1. In the VPC service sidebar, locate the Virtual Private Network menu and select Virtual Private Gateways.
2. Click Create Virtual Private Gateway.\\
![AWS Create Virtual Private Gateway form with name and ASN fields]()
3. Provide a Name tag.
* Set a name that helps you identify the gateway easily.
4. Select Amazon default ASN and click Create Virtual Private Gateway.
5. On the Virtual Private Gateways dashboard, right-click the newly created virtual private gateway and select Attach to VPC.\\
![AWS Virtual Private Gateways dashboard with Attach to VPC right-click option]()
Next, you need to manually enable route propagation for the virtual private gateway. For more information about VPN routing, see [Amazon VPC Documentation: Site-to-Site VPN Routing Options](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPNRoutingTypes.html).
1. In the VPC service sidebar, locate the Virtual Private Cloud menu and select Route Tables.\\
![AWS VPC sidebar with Route Tables option highlighted]()
2. In the list of routing tables, select the main route table for your VPC.
3. At the bottom of the screen, select Route Propagation.
* If your virtual private gateway is not listed, make sure that it's attached to the VPC.
4. Click Edit route propagation.\\
![AWS Route Table Route Propagation tab with Propagate checkbox and Edit button]()
5. Select the Propagate checkbox and click Save.
## Create the site-to-site VPN connection
After you have a customer gateway and a virtual private gateway in place, you can configure the site-to-site VPN connection. During setup, you need to select the customer gateway and the virtual private gateway that you want to use and configure routing. You need to route traffic to your internal, private network. By default, this is the Private-1 network. You can find the networking information for this network in **Appendix B** of your IP Plan.
1. In the VPC service sidebar, locate the Virtual Private Network menu and select Site-to-Site VPN Connections.\\
![AWS VPC sidebar with Site-to-Site VPN Connections option highlighted]()
2. Click Create VPN Connection.\\
![AWS Create VPN Connection form with gateway type, routing, and static IP fields]()
3. Provide Name tag.
4. For Target Gateway Type, select Virtual Private Gateway, and from the Virtual Private Gateway drop-down menu, select the virtual private gateway you created earlier.
5. Select that you want to use an Existing customer gateway, and from the Customer Gateway ID drop-down menu, select the customer gateway that you created earlier.
6. For Routing Options, select Static.
7. In Static IP Prefixes, provide the CIDR notation for the private network listed in Appendix A of the IP Plan (by default, the Private-1 network).
* For more information about CIDR notations, see [Understanding IP Addresses, Subnets, and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation). You can also use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
8. Do not edit the Tunnel Options section.
9. Click Create VPN Connection.
## Ensure that AWS allows inbound traffic
Based on your requirements and current setup, you might need to enable inbound traffic from MacStadium to AWS. For more information, see [Amazon VPC Documentation: Security Groups for Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) and [Amazon VPC Documentation: Network ACLs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html).
## Next steps
If you are ready to proceed, see [AWS VPN Config for Cisco ASA/ASAv](/iaas/aws/aws-vpn-config-for-cisco-asaasav).
# AWS-to-MacStadium VPN troubleshooting
Source: https://docs.macstadium.com/iaas/aws/aws-troubleshooting
If you encounter any issues during or after the configuration of your site-to-site VPN connection between AWS and MacStadium, check this list of common.
If you encounter any issues during or after the configuration of your site-to-site VPN connection between AWS and MacStadium, check this list of common issues and troubleshooting instructions.
## Errors During the Cisco ASA/ASAv Configuration
Sometimes, the command line interface might return errors about the crypto isakmp policy block of commands.
* **Workaround**: Ignore the errors. They do not affect the configuration.
The command-line interface returns `ERROR: unable to find interface "outside"`.
* **Workaround**: Sometimes, the command line interface is case-sensitive and you need to preserve the capitalization of the MacStadium network configuration as provided in the [IP Plan](/macstadium/macstadium-overview/ip-plan).
1. Clean up the ASA configuration.
* For more information, see Cleaning up the ASA/ASAv configuration.
2. Rename outside in your configuration file to the precise name of the outside interface of your Cisco ASA/ASAv device. By default, this is the Outside network.
* For more information, see [AWS VPN Config for Cisco ASA/ASAv](/iaas/aws/aws-vpn-config-for-cisco-asaasav).
3. Re-run the complete configuration in Cisco ASDM-IDM.
* For more information, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
## The Tunnel is UP but There's No Traffic Between AWS and MacStadium
If Amazon shows that one tunnel is UP but there's no traffic between AWS and your MacStadium private cloud, it might be because of some common mistakes when preparing the configuration file. Check for the following:
### AWS Checks
All checks in this section are performed in the AWS Management Console.
### Verify that your virtual private gateway is attached to the VPC.
1. Log in to your AWS Management Console and access your VPC service.
2. In the top right corner of the screen, make sure that you're working in the correct region.
3. In the VPC service sidebar, locate the Virtual Private Network menu and select Virtual Private Gateways.\\
![AWS VPC sidebar with Virtual Private Gateways option highlighted]()
4. On the Virtual Private Gateways dashboard, check the status of the virtual private gateway used in your site-to-site VPN.
5. If the virtual private gateway is detached, right-click it and select Attach to VPC.\\
![AWS Virtual Private Gateways dashboard with Attach to VPC right-click option]()
**Verify that the route tables for the Amazon Virtual Private Cloud (Amazon VPC) propagate traffic for the virtual private gateway you're using.**
For more information about route tables in Amazon, see [Amazon VPC Documentation: Route Tables](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html).
1. Log in to your AWS Management Console and access your VPC service.
2. In the top right corner of the screen, make sure that you're working in the correct region.
3. In the VPC service sidebar, locate the Virtual Private Cloud menu and select Route Tables.\\
![AWS VPC sidebar with Route Tables option highlighted]()
4. In the list of routing tables, select the main table.
* At the bottom of the screen, select **Route Propagation** and make sure that the propagation is enabled. If your virtual private gateway is not listed, make sure that it's attached to the VPC.
* If propagation is disabled, click **Edit route propagation**.
* Select the **Propagate** checkbox and click **Save**.
![AWS Route Table Route Propagation tab with Propagate checkbox enabled]()
### Cisco ASA/ASAv Checks
All checks in this section are performed against the site-to-site VPN configuration file downloaded from Amazon. For more information, see [AWS VPN Config for Cisco ASA/ASAv.](/iaas/aws/aws-vpn-config-for-cisco-asaasav)
**Verify that you've replaced `` and `` with the correct values for the internal, private network of your MacStadium private cloud.**
By default, this is the Private-1 network.
You can find the networking information for this network in Appendix A of your [IP Plan](/macstadium/macstadium-overview/ip-plan).
**Verify that you've configured the NAT exemption rule properly.**
* The host and subnet mask required for obj-SrcNet are the host and mask for the internal, private network of your MacStadium private cloud. By default, this is the Private-1 network. You can find the networking information for this network in Appendix A of your IP Plan.
* The host and subnet mask required for obj-amzn are the host and mask for your Amazon VPC. You can find this information by logging into your AWS Management Console, navigating to your VPC dashboard, selecting your VPC, and checking the Description at the bottom of the screen. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the /16 notation converts to a 255.255.0.0 subnet mask).
* The values in the brackets after nat must be the name of the internal, private network of your MacStadium private cloud, followed by the name of the outside interface of your Cisco ASA/ASAv device. By default, these are Private-1 and Outside, respectively. You can find the names of these networks in Appendix A of your IP Plan.
**To resolve any of the listed common problems with the Cisco ASA/ASAv configuration, complete the following steps:**
1. Clean up the firewall configuration.
* For more information, see Cleaning up the ASA/ASAv configuration.
2. Make the necessary changes to the configuration file.
* For more information, see [AWS VPN Config for Cisco ASA/ASAv](/iaas/aws/aws-vpn-config-for-cisco-asaasav).
3. Re-run the complete configuration in Cisco ASDM-IDM.
* For more information, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
## There's Traffic from AWS to MacStadium but You Cannot Access AWS from MacStadium
Sometimes, you might be able to establish an SSH connection from AWS to MacStadium but you might not be able to see or access AWS from MacStadium.
This might be due to AWS being configured to stop inbound traffic.
For information about how to enable inbound traffic, see [Amazon VPC Documentation: Security Groups for Your VPC ](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)and [Amazon VPC Documentation: Network ACLs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html).
## Troubleshooting
### Cleaning Up the ASA/ASAv Configuration
Sometimes, you might need to clean up the Cisco ASA/ASAv configuration and start over.
1. Verify that you are connected via VPN to your MacStadium private cloud.
* For more information about how to connect to the VPN, see [Connecting to Your Cloud (via VPN)](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
* For more information about how to log in to your firewall, see [Logging in to Your Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
3. In the Cisco ASDM-IDM application toolbar, select **Tools > Command Line Interface**.\\
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line.
5. Run the following commands one by one, clicking Send in between. Replace the placeholders with their respective values. Use **Table 1: Placeholders** for reference.
```
clear configure tunnel-group
clear configure tunnel-group
clear configure group-policy
clear configure crypto map
clear configure access-list
clear configure access-list amzn-filter
clear configure access-list acl-amzn (likely: acl-amzn)
clear configure crypto ipsec transform-set transform-amzn
clear configure sla monitor 1
no nat (,) 1 source static obj-SrcNet obj-SrcNet destination static obj-amzn obj-amzn
no object network obj-SrcNet
no object network obj-amzn
```
### Table 1: Placeholders
| Placeholder | Description | Example |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `` | The IP of the tunnel, configured with the first set of tunnel-group commands in the Amazon configuration file. | `192.168.0.0` |
| `` | The IP of the tunnel, configured with the second set of tunnel-group commands in the Amazon configuration file. | `192.168.0.0` |
| `` | The name of the policy configured with the group-policy commands in the Amazon configuration file. By default: filter. | `filter` |
| `` | The name of the crypto map configured with the crypto map commands in the Amazon configuration file. | `amzn_vpn_map` |
| `` | The unique name of the access control list created with the configuration file in the Amazon configuration file. | `outside_access_in` |
| `` | The name of the internal, private network of your MacStadium private cloud. By default, this is the Private-1 network. You can find the networking information for this network in Appendix A of your IP Plan. | `Private-1` |
| `` | The name of the outside interface of your Cisco ASA/ASAv device. By default, this is the Outside network. You can find the networking information for this network in Appendix A of your IP Plan. | `Outside` |
## More Troubleshooting by Amazon
For more detailed troubleshooting instructions, [see Amazon VPC Documentation: Troubleshooting Cisco ASA Customer Gateway Connectivity](https://docs.aws.amazon.com/vpc/latest/adminguide/Cisco_ASA_Troubleshooting.html).
## More Troubleshooting by Cisco
For more detailed troubleshooting instructions, see [Cisco Documentation: IPsec Troubleshooting](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html).
# AWS VPN Config for Cisco ASA/ASAv
Source: https://docs.macstadium.com/iaas/aws/aws-vpn-config-for-cisco-asaasav
Complete an AWS-MacStadium site-to-site VPN by configuring your Cisco ASA/ASAv. Download and fill in the Amazon-generated config file, then apply it.
## About
After creating a [site-to-site VPN connection in Amazon](/iaas/aws/site-to-site-vpn-configuration-with-aws), customers must configure the Cisco firewall to recognize the connection and let traffic into MacStadium Private Cloud.
## Overview
Amazon provides a semi-prefilled configuration file with very detailed instructions. The configuration file must be downloaded and provide any missing information (indicated by placeholders). Afterwards, the configuration can be applied to the Cisco ASA/ASAv to complete the Site-to-Site VPN setup.
## Getting Started
**Amazon Configuration Download**
Amazon lets you download pre-filled configurations for a variety of vendors. The default firewall vendor for MacStadium private clouds is Cisco Systems, Inc.
1. Verify that you have created a site-to-site VPN connection in Amazon.
* For more information about how to set up your VPN, see [Setting Up the AWS Side of the Site-to-Site VPN](/iaas/aws/site-to-site-vpn-configuration-with-aws).
2. Log in to your AWS Management Console and access your VPC service.
3. In the top right corner of the screen, make sure that you're working in the correct region.
4. In the VPC service sidebar, locate the Virtual Private Network menu and select Site-to-Site VPN Connections.\\
![AWS VPC sidebar with Site-to-Site VPN Connections option highlighted]()
5. In the list, select your newly created VPN connection and click Download Configuration.\\
![AWS Site-to-Site VPN Connections list with Download Configuration button highlighted]()
6. For Vendor, select Cisco Systems, Inc.
7. For Platform, select ASA 5500 Series.
8. For Software, select ASA 9.x for a policy-based VPN OR ASA 9.7 + VTI for a route-based VPN.\\
![AWS Download Configuration dialog with Cisco Systems vendor and ASA platform selected]()
## Fill in the configuration blanks
Unless you have extensive experience with AWS and ASA/ASAv configurations, follow the instructions in the configuration file to the letter. Otherwise, your site-to-site VPN might not work as expected.
You need to manually replace the placeholders in the configuration file you downloaded from Amazon with the values for your MacStadium configuration.
**Table 1: Configuration parameters**
| Placeholder | Description | More information | Example |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `` | The name of the outside interface of your Cisco ASA/ASAv device as provided in **Appendix A** of your IP Plan. By default, the value is `Outside`. | [The IP Plan](/macstadium/macstadium-overview/ip-plan) | `Outside` |
| `` | A unique name for the access control list that permits the creation of the tunnel and the traffic over it. | [Cisco Documentation: Cisco Access Control Lists](https://www.cisco.com/c/en/us/support/docs/security/ios-firewall/23602-confaccesslists.html) | `outside_access_in` |
| `` | The IPv4 address of your Amazon VPC (without the subnet mask bit notation). | You can get this value by logging in to your AWS Management Console, navigating to your VPC dashboard, selecting your VPC, and checking the **Description** at the bottom of the screen. | `192.168.0.0` |
| `` | The subnet mask for your Amazon VPC. | You can get this value by logging in to your AWS Management Console, navigating to your VPC dashboard, selecting your VPC, and checking the **Details** at the bottom of the screen. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the `/16` notation converts to a `255.255.0.0` subnet mask). | `255.255.0.0` |
| `` | A unique name for the crypto map. If you already have other crypto maps configured, you need to change the mapping number. | [Cisco Documentation: Configuring Crypto Maps](https://www.cisco.com/c/en/us/td/docs/security/vpn_modules/6342/vpn_cg/6342site3.html#wp1036915) | `amzn_vpn_map`. |
| `` | An IP address in your Amazon VPC that can serve as an SLA monitor keeping the site-to-site tunnel alive. | You can set this to the `` address plus one. For example: if your `` is `192.168.0.0`, use `192.168.0.1` for your ``. | `192.168.0.1` |
| `` | The IP address for the internal private network of your MacStadium cloud as provided in **Appendix A** of your IP Plan. By default, this is the `Private-1` network. | [The IP Plan](/macstadium/macstadium-overview/ip-plan) | `192.168.0.0` |
| `` | The subnet mask for the internal private LAN of your MacStadium cloud as provided in **Appendix A** of the IP Plan. By default, this is the `Private-1` network. | [The IP Plan](/macstadium/macstadium-overview/ip-plan) | `255.255.0.0` |
1. Verify that you have downloaded the configuration file from your AWS Management Console.
2. Open the configuration file.
3. Replace all placeholders with their respective values. Use Table 1: Configuration parameters for reference.
4. Uncomment the line: access-list amzn-filter extended permit ip .... To uncomment, remove ! at the start of the line.
5. Uncomment the lines for object and nat configuration at the end of the config file. To uncomment, remove ! at the start of the line.
6. Keep the following line. This ensures the SLA monitor works as expected.
```
object network obj-SrcNet
subnet 0.0.0.0 0.0.0.0
```
* Note that based on your network configuration and requirements, you can modify this line to map to the subnet and the subnet mask for the Private-1 network from your IP Plan. If you choose to modify this line, do not configure the `` value.
7. On the following line, change 0.0.0.0 0.0.0.0 to a combination of the IP address and the subnet mask for your Amazon VPC.
* You can get these values by logging in to your AWS Management Console, navigating to your VPC dashboard, selecting your VPC, and checking the Description at the bottom of the screen. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the /16 notation converts to a 255.255.0.0 subnet mask).
* For example
```
object network obj-amzn
subnet 0.0.0.0 0.0.0.0
TO
object network obj-amzn
subnet 192.168.0.0 255.255.0.0
```
8. On the following line, change inside and outside to the names of the internal private network and the outside interface of your MacStadium private cloud, respectively, as provided in Appendix A of your IP Plan. By default, these are Private-1 and Outside, respectively.
```
nat (inside,outside) 1 source static obj-SrcNet obj-SrcNet
destination static obj-amzn obj-amzn
TO
nat (Private-1,Outside) 1 source static obj-SrcNet obj-SrcNet
destination static obj-amzn obj-amzn
```
9. (Optional) Delete the remaining commented lines to clean up the file. Commented lines are indicated by ! at the beginning of the line.
10. Save your changes.
### Configure TCP State Bypass (Route-based VPN only)
If you selected **ASA 9.7 + VTI** (route-based VPN), you need to enable the TCP State Bypass feature. This allows outbound and inbound traffic to flow through separate VPN tunnels, which is required for HA VPN scenarios where both tunnels are active simultaneously.
**Table 2: TCP State Bypass parameters**
| Placeholder | Description | More information | Example |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `` | A unique name for the access control list that permits the creation of the tunnel and the traffic over it. | [Cisco Documentation: Access Control Lists](https://www.cisco.com/c/en/us/support/docs/security/ios-firewall/23602-confaccesslists.html) | `acl-state-bypass` |
| `` | A unique name for the class map that identifies the traffic for which to disable stateful firewall inspection. | [Cisco Documentation: TCP State Bypass](https://www.cisco.com/c/en/us/td/docs/security/asa/asa-cli-reference/A-H/asa-command-ref-A-H.html) | `cm-state-bypass` |
| `` | A unique name for the policy map that assigns actions to the specified class map traffic. | [Cisco Documentation: TCP State Bypass](https://www.cisco.com/c/en/us/td/docs/security/asa/asa-cli-reference/A-H/asa-command-ref-A-H.html) | `pm-state-bypass` |
| `` | The name of the internal private interface of your Cisco ASA/ASAv device as provided in Appendix A of your IP Plan. By default, this is `Private-1`. | The IP Plan | `Private-1` |
1. Define an access list with the source and destination networks:
```
access-list extended permit ip
```
2. Create a class map to identify the traffic for which you want to disable stateful firewall inspection:
```
class-map
match access-list
```
3. Create a policy map to assign the TCP State Bypass action to the class map:
```
policy-map
class
set connection advanced-options tcp-state-bypass
```
4. Apply the policy map to your private interface:
```
service-policy interface
```
5. Save your changes.
## Next steps
If you are ready to feed the complete configuration into your Cisco ASA/ASAv, see [Setting Up the MacStadium Side of the Site-to-Site VPN](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
# Site-To-Site VPN Configuration with AWS
Source: https://docs.macstadium.com/iaas/aws/site-to-site-vpn-configuration-with-aws
Configure a site-to-site IPsec VPN between AWS and MacStadium with Cisco ASA TCP State Bypass for HA VPN and BGP routing scenarios.
## Overview
The goal of this documentation is to update the Site-To-Site VPN configuration with AWS and add specific configuration details for the Cisco Adaptive Security Appliance (ASA) feature TCP State-bypass, which is required in HA VPN scenarios (HA-VPN is a regional per VPC VPN solution. HA-VPN gateways have two interfaces, each with their own public IP address).
* A one-time or temporary access to the MacStadium cloud from a single virtual or physical machine is required.
* Cisco AnyConnect VPN is recommended.
* For more information, see [Connecting to Your Cloud (via VPN)](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn)
## Creating Stable IPSec Site-to-Site VPN
1. Check the software version and model of the Cisco ASA/ASAv device of the MacStadium cloud.
2. Configure the private cloud to connect to your MacStadium cloud. One or more of the following must be configured:
* Provide the public endpoint of the MacStadium cloud.
* This is the public network IP listed for the FW1-Outside network in Appendix B of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* Enable policy-based routing between the private cloud and the internal private network the MacStadium cloud (default the Private-1 network).
* This is the private network host and range listed in Appendix A of the IP Plan.
* Enable inbound traffic to the private cloud.
3. Set up the Cisco ASA/ASAv device of the MacStadium cloud. One or more of the following must be configured:
* A nat exemption rule for traffic between the two clouds.
* This allows traffic from the private cloud to the private network and the outside interface of the MacStadium cloud. By default, these are respectively the Private-1 and Outside networks listed in Appendix A of the IP Plan.
* `access-list` rules permitting traffic from the private cloud to the public endpoint of the MacStadium cloud.
* By default, this is the FW1-Outside network listed in Appendix B of the IP Plan.
* A crypto map rule that maps traffic between the two clouds.
* By default, this is the Outside network listed in Appendix A of the IP Plan.
* IPSec and IKE policies.
* `tunnel-group` rules that point to the private cloud that connect to the MacStadium cloud.
4. Prepare these settings based on the Cisco ASA/ASAv software and model
For more information about how to configure each aspect of your Cisco firewall, see Cisco Documentation: [Configuration Guides](https://www.cisco.com/c/en/us/support/security/asa-5500-series-next-generation-firewalls/products-installation-and-configuration-guides-list.html).
### Helpful Links
Cisco Documentation: [Navigating the Cisco ASA Series Documentation](https://www.cisco.com/c/en/us/td/docs/security/asa/roadmap/asaroadmap.html)
Cisco Documentation: [Managing Site-to-Site VPNs: The Basics](https://www.cisco.com/c/en/us/obsolete/security/cisco-security-manager-4-1.html)
Cisco Documentation: [Cisco ASA Series Syslog Messages](https://www.cisco.com/c/en/us/td/docs/security/asa/syslog/b_syslog.html)
[Logging into Your Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall)
## Networking Setup for Private Cloud
Because of the highly customizable nature of on-premises private clouds, this guide is not exact steps but rather general guidelines.
A one-time or temporary access must be established from a single virtual or physical machine to the MacStadium cloud. It is recommended to use Cisco AnyConnect VPN. For more information, see [Connect to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
To establish a stable and persistent connection, between the entire private cloud to the MacStadium cloud, then establish an **IPsec Site-To-Site VPN** between the two clouds.
## Creating IPSec Site-To-Site VPN between Two Clouds
1. Check and document the software version and model of the Cisco ASA/ASAv device for the MacStadium cloud.
2. Configure the private cloud to connect to the MacStadium cloud.
* One or more of the following might need to be configured.
* Provide the public endpoint of the MacStadium cloud.
* Usually, this is the public network IP listed for the FW1-Outside network in Appendix B of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* Enable routing between the private cloud and the internal private network of the MacStadium cloud (by default, the Private-1 network).
* Usually, this is the private network host and range listed in Appendix A of the IP Plan.
* Enable inbound traffic to the private cloud.
3. Set up the Cisco ASA/ASAv device of the MacStadium cloud.
* You might need to configure one or more of the following rules:
* A NAT exemption rule for traffic between the two clouds. It might need to allow traffic from the private cloud to the private network and the outside interface of the MacStadium cloud. By default, these are respectively the Private-1 and Outside networks listed in Appendix A of the IP Plan.
* NAT exemption allows the ability to exclude traffic from being translated with NAT. One scenario where this is typically done is for a site-to-site VPN tunnel.
* Access-list rules permitting traffic from the private cloud to the public endpoint of your MacStadium cloud. By default, this is the FW1-Outside network listed in Appendix B of the IP Plan.
* A crypto map rule that maps traffic between the two clouds. Usually, this is mapped to the outside interface of the MacStadium cloud. By default, this is the Outside network listed in Appendix A of the IP Plan.
* IPSec and IKE policies.
* Tunnel-group rules that point to the private cloud to connect to the MacStadium cloud.
* The TCP State Bypass feature, which requires an access-list, class-map, policy-map, and a service-policy. This is a requirement for Site-To-Site VPN with Virtual Tunnel Interfaces only and is configured to allow asynchronous routing between separate VPN tunnels.
These settings must be based on the Cisco ASA/ASAv software and model. For more information about how to configure each aspect of your Cisco firewall, see [Cisco Documentation: Configuration Guides](https://www.cisco.com/c/en/us/support/security/asa-5500-series-next-generation-firewalls/products-installation-and-configuration-guides-list.html).
## Networking Setup AWS
To establish a stable, persistent connection between Amazon Virtual Private Cloud (Amazon VPC) and the MacStadium private cloud, configure an IPsec Site-To-Site VPN between the two clouds.
There are two VPN configuration options available, Policy-based and Route-based (VTI) VPN;
* Policy-based VPN, there are two VPN tunnels where in AWS one tunnel is active (up), and one is passive (down). A monitoring service checks frequently if the active tunnel is up and, if not, brings the passive tunnel up, what ensures minimal downtime.
* Route-based (VTI) VPN, both tunnels are active at the same time and can route traffic in and out simultaneously. Also, this allows routing between MacStadium and AWS to be configured statically or dynamically with BGP. Route-based VPN is the preferred option as it offers enhanced routing and monitoring control.
## Creating Site-To-Site VPN
This is done from an Amazon VPC to the MacStadium private cloud.
1. Log into the VPC service.
2. Create a customer gateway.
3. Set up a virtual private gateway.
4. Create the Site-To-Site VPN connection.
5. Ensure that AWS allows inbound traffic.
## Creating Customer Gateway
In AWS, the customer gateway represents the MacStadium endpoint of the Site-To-Site VPN connection. When you configure the customer gateway, use the networking information of the public network. By default, this is the FW1-Outside network. The networking information for this network in your [IP plan](/macstadium/macstadium-overview/ip-plan).
For more information about the customer gateway, see Amazon VPC Documentation: Components of Your Site-To-Site VPN.
1. In the VPC service sidebar, locate the Virtual Private Network (VPN) menu and select Customer gateways.\\
![AWS VPC sidebar with Customer gateways option highlighted]()
2. Click Create Customer Gateway.
3. Provide a Name. Set a name that is easy to remember.
4. In BGP ASN, use a private ASN in the range of 64,512–65,534. This is used later as the BGP process number in the MacStadium firewall.
5. In the IP Address text box, provide the IP address of the public network listed in Appendix B of the IP Plan. By default, this is the FW1-Outside network.
6. Keep the other options with the default values and click Create Customer Gateway.
![AWS Create Customer Gateway form with BGP ASN and IP address fields]()
## Setting Up Virtual Private Gateway
In AWS, the virtual private gateway represents the Amazon endpoint of the Site-To-Site VPN connection.
For more information about the virtual private gateway, see [Amazon VPC Documentation: Components of Your Site-To-Site VPN](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPC_VPN.html#VPN).
1. In the VPC service sidebar, locate the Virtual Private Network (VPN) menu and select Virtual Private Gateways.
2. Click Create Virtual Private Gateway.
3. Provide a Name tag. Set a name that is easy to remember.
4. Select Amazon default ASN and click Create Virtual Private Gateway.
5. Connect to the VPN.
* After signing up, the [IP Plan](/macstadium/macstadium-overview/ip-plan) is sent. Review that information to configure access to the cloud environment. The recommended method of gaining access is via a Virtual Private Network (VPN), which is both easy to implement and secure.\\
![AWS VPC sidebar with Virtual Private Gateways option highlighted]()
6. On the Virtual Private Gateways dashboard, right-click the newly created virtual private gateway and select Attach to VPC.\\
![AWS Virtual Private Gateways dashboard with Attach to VPC right-click option]()
7. Select the VPC to attach the Virtual Private Gateway to and click Attach to VPC.\\
![AWS Attach to VPC dialog with VPC dropdown and Attach button]()
8. Select the Propagation Enable checkbox.
9. Click Save.\\
![AWS Route Table Route Propagation tab with Propagate checkbox]()
## Creating Site-To-Site VPN Connection
If the customer gateway and a virtual private gateway are in place, then configure the Site-To-Site VPN connection.
During setup, select the customer gateway and the virtual private gateway to use, and configure that routing.
Route traffic to the internal, private network. By default, this is the Private-1 network. The networking information for this network is in Appendix A of the IP Plan.
1. In the VPC service sidebar, locate the Virtual Private Network menu and select Site-To-Site VPN Connections.
2. Click Create VPN Connection.
3. Provide Name tag.
4. For Target Gateway Type, select Virtual Private Gateway.
5. For Virtual Private Gateway, select the virtual private gateway that was created earlier.
6. Select Existing customer gateway, and from the Customer Gateway ID dropdown menu, select the customer gateway that was created earlier.
7. Select the Routing Options:
* Static manually specifies the destination subnets of the VPN.
* Select static routing and provide in Static IP Prefixes the CIDR notation for the private network listed in Appendix A of the IP Plan (by default, the Private-1 network). To convert the subnet mask to a CIDR notation, use a CIDR calculator. Example: 10.221.254.0/24
* Dynamic (requires BGP) and dynamically exchanges routes between AWS and MacStadium environments.
* Select dynamic routing to keep the default values and proceed to the next step.
* For more information about AWS VPN tunnel options, see: [Amazon VPC Documentation](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPNTunnels.html).
8. Do not edit the Tunnel Options section.
9. Click Create VPN Connection.\\
![AWS Create VPN Connection form with gateway type and routing settings]()
## Allowing AWS Inbound Traffic
Based on the requirements and current setup, it might be necessary to enable inbound traffic from MacStadium to AWS.
For more information, see Amazon VPC Documentation: Security Groups for Your VPC and [Amazon VPC Documentation: Network ACLs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html).
## AWS VPN Configuration for Cisco ASA/ASAv
Proceed with the [AWS VPN configuration for Cisco.](/iaas/aws/aws-vpn-config-for-cisco-asaasav)
After creating the Site-To-Site VPN connection in Amazon, configure the Cisco firewall to recognize the connection and let traffic into the MacStadium private cloud.
Amazon provides a prefilled configuration file with very detailed instructions. Download the configuration file and provide any missing information (indicated by placeholders). Then feed the configuration into the Cisco ASA/ASAv to complete the Site-To-Site VPN setup.
1. Download the configuration from Amazon
2. Fill in the configuration blank
## Downloading Amazon Configuration
Amazon has prefilled configurations ready for download, from a variety of vendors. The default firewall vendor for MacStadium private clouds is Cisco Systems, Inc.
1. Verify there is a Site-To-Site VPN connection in Amazon.
* For more information about how to set up your VPN, see [Setting Up the AWS Side of the Site-To-Site VPN](/iaas/aws/aws-networking-setup).
2. Log in to the AWS Management Console and access your VPC service, which is located in the top right corner of the screen.
3. In the VPC service sidebar, locate the Virtual Private Network menu and select Site-To-Site VPN Connections.
4. In the list, select the newly created VPN connection and click Download Configuration.
5. Vendor, select Cisco Systems, Inc.
6. Platform, select ASA 5500 Series.
7. Software:
* For a policy-based VPN, select ASA 9.x
* For a route-based VPN, select ASA 9.7 + VTI
If ASA 9.7 + VTI was selected, choose ikev2 as the IKE version and click Download.
![AWS Download Configuration dialog with Cisco Systems vendor and ASA platform selected]()
## Configuration Blanks
Do not attempt AWS and ASA/ASAv configuration without proper experience, or unexpected consequences may happen.
Manually replace the placeholders in the configuration file that were downloaded from Amazon (with the values for the MacStadium configuration). Policy-based VPN - ASA 9.x
Make sure that the name of all configuration elements in this script are unique, not currently in use in your environment.
## Configuration Parameters
| Placeholder Example | Description | More Information | Example |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `` | The IPv4 address of the Amazon VPC (without the subnet mask bit notation). | This value can be found by logging in to the AWS Management Console and navigating to the VPC dashboard. Select the VPC and checking the Description at the bottom of the screen. | 172.31.0.0 |
| `` | The subnet mask for the Amazon VPC. | This value can be found by logging in to the AWS Management Console, and navigating to the VPC dashboard. Select the VPC, and check the Details at the bottom of the screen. Then convert the subnet mask bit notation to the correct subnet mask (for example, the /16 notation converts to a 255.255.0.0 subnet mask). | 255.255.0.0 |
| `` | A unique name for the crypto map. If there is already a crypto maps configured, then change the mapping number. | [Cisco Documentation: Configuring Crypto Maps](https://www.cisco.com/c/en/us/td/docs/security/vpn_modules/6342/vpn_cg/6342site3.html#wp1036915) | amzn\_vpn\_map |
| `` | An IP address in the Amazon VPC that can serve as an SLA monitor keeping the Site-To-Site tunnel alive. | Set this to an available host in the AWS VPC. The host must reply to ICMP echo requests. | 172.31.0.5 |
| `` | The IP address for the internal private network of the MacStadium cloud as provided in Appendix A of your IP Plan. By default, this is the Private-1 network. | [The IP Plan](/macstadium/macstadium-overview/ip-plan) | 10.221.254.0 |
1. Verify the configuration file from the AWS Management Console.
2. Open the configuration file.
3. Replace all placeholders with their respective values. Use Configuration parameters for reference.
4. Uncomment the line: `access-list amzn-filter extended permit ip`. To uncomment, remove `!` at the start of the line.
5. Uncomment the lines for object and nat configuration at the end of the config file.
* To uncomment, remove ! at the start of the line.
* Keep the following line to ensure the SLA monitor works as expected.
* `object network obj-SrcNet subnet 0.0.0.0 0.0.0.0`
Based on the network configuration and requirements, the line can be modified to map to the subnet and the subnet mask for the Private-1 network from your IP Plan. If this line is modified, then do not configure the `` value.
6. On the following line, change 0.0.0.0 0.0.0.0 to a combination of the IP address and the subnet mask for your Amazon VPC.
* These values are in the AWS Management Console. Navigate to the VPC dashboard and select the VPC, and check the Description at the bottom of the screen.
* Convert the subnet mask bit notation to the correct subnet mask (for example, the /16 notation converts to a 255.255.0.0 subnet mask).
* For example:
* object network obj-amzn subnet 0.0.0.0 0.0.0.0
```
* change to:
* object network obj-amzn subnet 192.168.0.0 255.255.0.0
```
7. On the following line, change inside and outside to the names of the internal private network and the outside interface of the MacStadium private cloud, respectively, as provided in Appendix A of the IP Plan. By default, these are Private-1 and Outside, respectively.
* nat (inside,outside) 1 source static obj-SrcNet obj-SrcNet destination static obj-amzn obj-amzn
to
* nat (Private-1,Outside) 1 source static obj-SrcNet obj-SrcNet destination static obj-amzn obj-amzn
8. (**Optional**) Delete the remaining commented lines to clean up the file. Commented lines are indicated by ! at the beginning of the line.
9. Save the changes.
## Configuration Parameters for Route-based VPN - ASA 9.7 + VTI
| Placeholder Examples | Description | More Information | Example |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `` | The name of the outside interface of the Cisco ASA/ASAv device as provided in Appendix A of your IP Plan. By default, the value is Outside. | [The IP Plan](/macstadium/macstadium-overview/ip-plan) | Outside |
| `` | The IP address for the internal private network of your MacStadium cloud as provided in Appendix A of your IP Plan. By default, this is the Private-1 network. | [The IP Plan](/macstadium/macstadium-overview/ip-plan) | 10.221.254.0 |
| `` | The subnet mask for the internal private LAN of the MacStadium cloud as provided in Appendix A of the IP Plan. By default, this is the Private-1 network. | [The IP Plan](/macstadium/macstadium-overview/ip-plan) | 255.255.255.0 |
| `` | The IPv4 address of the Amazon VPC (without the subnet mask bit notation). | This value can be found by logging in to the AWS Management Console, and navigate to your VPC dashboard. Select the VPC and check the Description at the bottom of the screen. | 172.31.0.0 |
1. Verify the configuration file from the AWS Management Console.
2. Open the configuration file.
3. Replace the placeholders with their respective values. Currently, only the placeholder `` is available in the AWS script. Use Table 1: Configuration parameters for reference.
4. Change the name of the tunnel interfaces. Example:
```
* interface tunnel 100 nameif aws-vpn-1 interface tunnel 200 nameif aws-vpn-2
```
5. Replace the network address and mask on the BGP configuration. Example: router bgp 65513 address-family ipv4 unicast network `` mask ``
6. Replace the placeholders with their respective values.
7. For a route-based VPN, enable the TCP State Bypass feature to allow the outbound and inbound traffic to flow through separate VPN tunnels as follows:
| Placeholder Example | Description | More Information | Example |
| -------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------- |
| `` | A unique name for the access control list that permits the creation of the tunnel and the traffic over it. | Cisco Documentation: Access Control Lists | acl-state-bypass |
| `` | A unique name for the Class-map. | Cisco Documentation: TCP State Bypass | cm-state-bypass |
| `` | A unique name for the access control list that permits the creation of the tunnel and the traffic over it. | Cisco Documentation: TCP State Bypass | pm-state-bypass |
* Define the Access list with the source and destination networks: access-list `` extended permit ip
* `` `` `` ``
* Create the Class Map to identify the traffic for which you want to disable stateful Firewall inspection:
* `class-map `
* Enter the match parameter command to specify the traffic of interest within the class map:
* `match access-list `
* Enter the policy-map name command to assign the actions to be taken in regards to the specified class map traffic:
* `policy-map class set connection advanced-options tcp-state-bypass`
* Enter the service-policy command in global configuration mode to activate the policy map on the targeted interface:
* `service-policy interface `
8. Save changes
## Completing Cisco ASA/ASAv Configuration
To complete configuration into the Cisco ASA/ASAv, see Setting Up the [MacStadium Side of the Site-To-Site VPN](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
## Manually Enabling Route Propagation
Manually enable route propagation for the virtual private gateway.
For more information about VPN routing, see [Amazon VPC Documentation: Site-To-Site VPN Routing Options](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPNRoutingTypes.html).
1. In the VPC service sidebar, locate the Virtual Private Cloud menu and select Route Tables.\\
![AWS VPC sidebar with Route Tables option highlighted]()
2. In the list of routing tables, select the main route table for your VPC.
3. Select Route Propagation. If the virtual private gateway is not listed, then make sure that it is attached to the VPC.
4. Click Edit route propagation.\\
![AWS Route Table Route Propagation tab with Edit route propagation button]()
## (Open-Source Option) OpenConnect
### Why OpenConnect?
For mostly CLI users, use [OpenConnect](https://www.infradead.org/openconnect/index.html) - an open-source VPN client available from the command line.
## Download and Install OpenConnect
If Homebrew is enabled, then run `brew install openconnect` from the command line.
For Windows users, download ([build](https://www.infradead.org/openconnect/download.html)) the [OpenConnect package or use Cisco AnyConnect](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
### Cisco AnyConnect alternative
Cisco firewalls are designed to work with the [Cisco AnyConnect Secure Mobility Client ](https://www.cisco.com/c/en/us/support/security/anyconnect-secure-mobility-client/series.html)as a VPN client. Users who prefer a GUI VPN client or prefer running on Windows, use Cisco AnyConnect.
* [Download and use Cisco AnyConnect](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn)
## Download AnyConnect
1. Download a VPN client. The recommend VPN client for MacStadium Private Clouds is Cisco AnyConnect.
2. Open MacStadium Portal > Account Menu > Files.
3. Open the file and locate the VPN Server section.
4. From the browser, visit `https://`.
Firefox is required to get past the self-signed certificate blocker.
5. When prompted, provide the VPN credentials from the IP Plan.
6. After log in, download a licensed version of AnyConnect directly from the firewall.
## Setup Process
1. Log in using the username and password from the IP Plan.
2. Cisco AnyConnect SecureMobility checks to see if Java is installed.
* If Java is installed, then Java is used.
* If Java is not installed, then a link for download is provided.
3. Follow the installation prompts to complete the install.
4. Once installation has completed:
* Select Settings
* Uncheck “Block connections to untrusted servers,” as the Cisco ASA appliance by default will be using a self signed certificate.
5. From the main screen, enter the IP Address provided in the IP Plan.
6. Click connect.
7. Enter your username and password to confirm the connection.
# Verify your AWS-to-MacStadium VPN connection
Source: https://docs.macstadium.com/iaas/aws/verify-aws
Verify your AWS-to-MacStadium site-to-site VPN is working by checking ISAKMP and IPsec security associations in Cisco ASDM-IDM using show crypto commands.
Verify that there is an ISAKMP security association between the peers.
1. Verify that you are connected via VPN to your MacStadium private cloud.
* For more information about how to connect to the VPN, see [Connecting to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
* For more information about how to log in to your firewall, see [Logging into Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
3. In the Cisco ASDM-IDM application toolbar, select **Tools > Command Line Interface**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line, enter the following command, and click **Send**.
```
show crypto isakmp sa
```
If the site-to-site VPN connection is configured properly, you should see information about an active IKEv1.
For more information about this verification command, see [Cisco Documentation: show crypto isakmp sa](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#isakmp_sa).
## Verify that there is an IPsec security association between peers
1. Verify that you are connected via VPN to your MacStadium private cloud.
* For more information about how to connect to the VPN, see [Connecting to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
* For more information about how to log in to your firewall, see [Logging into Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
3. In the Cisco ASDM-IDM application toolbar, select Tools > Command Line Interface\\
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line, enter the following command, and click Send.
```
show crypto ipsec sa
```
If the site-to-site VPN connection is configured properly, you should see a detailed log.
For more information about this verification command, see [Cisco Documentation: show crypto ipsec sa](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#ipsec_sa).
## Verify that one tunnel is up
1. Log in to your AWS Management Console and access your VPC service.
2. In the top right corner of the screen, make sure that you're working in the correct region.
3. In the sidebar, locate the Virtual Private Network menu and select Site-to-Site VPN Connections.\\
![AWS VPC sidebar with Site-to-Site VPN Connections option highlighted]()
4. Select your VPN from the list and inspect the details at the bottom of the screen.
5. Click Tunnel Details and verify that one of the tunnels is up.\\
![AWS VPN Tunnel Details tab showing one tunnel with status Up]()
## Test traffic and visibility through the tunnel
Follow the instructions provided in [Amazon VPC Documentation: How to Test the Customer Gateway Configuration](https://docs.aws.amazon.com/vpc/latest/adminguide/Cisco_ASA.html#TestCustomerGateway_ASA).
## Troubleshooting
See our [AWS Troubleshooting](/iaas/aws/aws-troubleshooting) doc for some common issues with AWS-MacStadium Site-to-Site VPN Connections.
# Azure Networking Setup
Source: https://docs.macstadium.com/iaas/azure/azure-networking-setup
Set up a policy-based IPsec VPN between Azure and MacStadium. Covers virtual network gateway, local network gateway, and connection configuration.
To establish a stable, persistent connection between a Microsoft Azure private cloud and your MacStadium private cloud, you need to configure a policy-based IPsec site-to-site VPN between the two clouds.
Currently, Azure lets you create a site-to-site VPN with one tunnel. To ensure minimal downtime (up to a minute or minute and a half), the Azure VPN gateway consists of two instances in an active-standby configuration. The standby instance automatically takes over when an issue with the active instance occurs.
For information about how to enable higher availability, see Azure Documentation: Highly Available Cross-Premises Connectivity.
To create a site-to-site VPN from your Azure private cloud to your MacStadium private cloud, you need to go through the following high-level steps:
## Log into Azure
1. Log in to the Azure portal with your credentials.
2. In the top right corner of the screen, make sure that you're working in the correct account and organization.
## Create an Azure virtual network
If you already have an Azure virtual network configured, you can skip this step.
Azure virtual networks let you manage connectivity for your Azure cloud resources. Any Azure virtual machines that you want to connect to from MacStadium must be on the Azure virtual network that sits at the Azure end of your VPN connection.
For more information about virtual networks, see [Azure Documentation: What is Azure Virtual Network?](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-overview)
1. Verify that you have a resource group in Azure.
2. In the search box at the top of the screen, type Virtual networks and select the respective entry in the filtered search results. Azure filters results as you type.\\
![Azure search results with Virtual networks entry highlighted]()
3. On the Virtual networks screen, click + Add.
4. Provide a Name.
5. For Address space, provide a range of IP addresses in the CIDR notation that can be used within the network. You must provide an IP range reserved for private use. For more information about the private IP range requirement, see [Azure Documentation: Designing networking for Microsoft Azure IaaS](https://docs.microsoft.com/en-us/office365/enterprise/designing-networking-for-microsoft-azure-iaas#step-4-determine-the-address-space-of-the-vnet).
* For more information about CIDR notations, see [Understanding IP Addresses, Subnets, and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation). You can also use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
6. Select Subscription, Resource group, and Location.
7. Provide a Subnet > Name or use the pre-filled default value.
8. For Subnet > Name, provide a subset of the Address space in CIDR notation.
9. (Optional) Modify the remaining pre-filled settings to match your requirements.
10. Click Create and wait for the deployment to complete.
* This might take a while. When the deployment is complete, the virtual network becomes listed under All resources.
## Example: Create an Azure virtual network
This image shows a sample Azure virtual network configuration.
![Sample Azure virtual network configuration form]()
## Create a gateway subnet
If you already have a gateway subnet configured for your Azure virtual network, you can skip this step.
After the deployment of your virtual network is complete, you need to create a gateway subnet. The gateway subnet consists of IPs that will be used by the gateway service.
1. On the Virtual Networks screen, select your virtual network, and click Subnets.
2. Click + Gateway subnet.\\
![Azure Virtual Networks Subnets tab with Gateway subnet button]()
3. In the Address range text box, provide an IP range for the subnet in the CIDR notation. This IP range must be a subset of the IP range for the virtual network subnet you created earlier.
* For more information about CIDR notations, see [Understanding IP Addresses, Subnets, and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation). You can also use a [CIDR calculator such as this CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
4. (Optional) Modify the remaining pre-filled settings to match your requirements.
5. Click OK and wait for the deployment to complete.
* This might take a while.
### **Example: Create a gateway subnet**
This image shows a sample configuration for the gateway subnet of an Azure virtual network.
![Sample gateway subnet configuration for an Azure virtual network]()
## Create a virtual network gateway
In Azure, the virtual network gateway represents the Azure side of your site-to-site VPN tunnel.
1. In the search box at the top of the screen, type Virtual network gateways and select the respective entry in the filtered search results.
* Azure filters results as you type.\\
![Azure search results with Virtual network gateways entry highlighted]()
2. On the Virtual network gateways screen, click + Add.
3. Select Subscription.
4. Select Virtual network.
* This action lets Azure pre-fill some of the remaining configuration.
5. Provide Name and select Region.
6. For Gateway type, select VPN.
7. For VPN type, select Policy-based.
8. Select your SKU.
* For more information about the available SKUs, see [Azure Documentation: Gateway SKUs](https://docs.microsoft.com/en-gb/azure/vpn-gateway/vpn-gateway-about-vpngateways#gwsku).
9. For Public IP address, select an existing unused IP address or create a new one.
10. Click Review + create, review the configuration, and click Create.
11. Wait for the deployment to complete.
* This might take a while.
12. Check if the virtual network gateway is deployed successfully.
* On the Virtual network gateways screen, select the virtual network gateway and click Properties.
* Verify that the Provisioning state is `Succeeded`.\\
![Azure virtual network gateway Properties showing Provisioning state Succeeded]()
### Example: Create a virtual network gateway
This image shows a sample configuration for a virtual network gateway.
![Sample Azure virtual network gateway configuration form]()
## Create a local network gateway
In Azure, the local network gateway represents the MacStadium side of your site-to-site VPN tunnel.
1. In the search box at the top of the screen, type Local network gateways and select the respective entry in the filtered search results.
* Azure filters results as you type.\\
![Azure search results with Local network gateways entry highlighted]()
2. On the Local network gateways screen, click + Add.
3. Provide a Name.
4. For IP Address, provide the IP address of the public network listed in Appendix B of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* By default, this is the `FW1-Outside` network.
5. For Address space, provide the IP range in CIDR notation of the private network listed in Appendix A of the IP Plan.
* By default, this is the `Private-1` network.
* For more information about CIDR notations, see [Understanding IP Addresses, Subnets, and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation). You can also use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
6. Leave Configure BGP settings deselected.
7. Select Subscription, Resource group, and Location.
8. Click Create.
9. Wait for the deployment to complete.
* This might take a while.
* When the deployment is complete, the local network gateway becomes listed under All resources.
## Create the VPN connection
With a virtual network gateway and a local network gateway in place, you can create and configure the VPN connection between Azure and your MacStadium private cloud.
1. In the search box at the top of the screen, type Local network gateways and select the respective entry in the filtered search results.
* Azure filters results as you type.
![Azure search results with Local network gateways entry highlighted]()
2\. On the Local network gateways screen, select the local network gateway you created earlier.
3\. From the sidebar menu, select Connections and click + Add.\\
![Azure local network gateway Connections sidebar with Add button]()
4\. Provide Name.
5\. Select Virtual network gateway.
6\. For Shared key (PSK), provide an IPSec pre-shared key that will be used to encrypt your data over the site-to-site VPN.
* You can use a generator tool such as the [IFM - IPSec Pre-shared Key (PSK) Generator](http://www.ifm.net.nz/cookbooks/IPSec-Pre-shared-Key-PSK-Generator.html).
Keep a record of the pre-shared key. You will need it later.
7. Review the remaining pre-filled settings and click OK.
8. Wait for the operation to complete.
* This might take a while.
* When the deployment is complete, the connection becomes listed under All resources.
At this point, the status of your newly created connection is Unknown.
### Example: Create the VPN connection
This image shows a sample configuration for the VPN connection.
![Sample Azure VPN connection configuration form]()
## Ensure that Azure allows inbound traffic
Based on your requirements and current setup, you might need to enable inbound traffic from MacStadium to Azure. For more information, see [Azure Documentation: Filter inbound traffic with Azure Firewall DNAT using the Azure portal](https://docs.microsoft.com/en-us/azure/firewall/tutorial-firewall-dnat) and [Azure Documentation: Security groups](https://docs.microsoft.com/en-us/azure/virtual-network/security-overview).
## Next steps
If you are ready to proceed with the MacStadium side of the configuration, see [Preparing the VPN Configuration for Input into Cisco ASA/ASAv](/iaas/azure/azure-vpn-config-for-cisco-asaasav).
# Azure Troubleshooting
Source: https://docs.macstadium.com/iaas/azure/azure-troubleshooting
If you encounter any issues during or after the configuration of your site-to-site VPN connection between Microsoft Azure and MacStadium, check this list.
If you encounter any issues during or after the configuration of your site-to-site VPN connection between Microsoft Azure and MacStadium, check this list of common issues and troubleshooting instructions.
* Unrecognized interface during the Cisco ASA/ASAv configuration
* The tunnel is connected but there's no traffic between Azure and MacStadium
* There's traffic from Azure to MacStadium but you cannot access Azure from MacStadium
## Unrecognized interface during the Cisco ASA/ASAv configuration
Sometimes, the command line interface might return ERROR: unable to find interface "outside". The command-line interface might be case-sensitive and you might need to preserve the capitalization of the MacStadium network configuration as provided in the [IP Plan](/macstadium/macstadium-overview/ip-plan).
1. Clean up the ASA configuration.
* For more information, see Cleaning up the ASA/ASAv configuration.
2. Rename outside in your configuration to the precise name of the outside interface of your Cisco ASA/ASAv device. By default, this is the Outside network.
* For more information, see [Azure VPN Config for Cisco ASA/ASAv](/iaas/azure/azure-vpn-config-for-cisco-asaasav).
3. Re-run the complete configuration in Cisco ASDM-IDM.
* For more information, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
## The tunnel is connected but there's no traffic between Azure and MacStadium
If Azure shows that the tunnel is Connected but there is no visibility and connectivity between the two clouds, it might be because of some common mistakes when preparing the configuration. Check for the following in the site-to-site VPN configuration. For more information, see [Azure VPN Config for Cisco ASA/ASAv](/iaas/azure/azure-vpn-config-for-cisco-asaasav).
* Verify that your \{ shared\_key } is correct. The \{ shared\_key } in the configuration must match the key set for the VPN connection.
* Verify that you've replaced \{ macstadium\_network\_address } and \{ macstadium\_network\_mask } with the correct values for the internal, private network of your MacStadium private cloud. By default, this is the Private-1 network.
* You can find the networking information for this network in Appendix A of your IP Plan.
* Verify that you've configured the NAT exemption rule properly.
* The host and subnet mask required for ONPREM-NET are the host and mask for the internal, private network of your MacStadium private cloud. By default, this is the Private-1 network. You can find the networking information for this network in Appendix A of your IP Plan.
* The host and subnet mask required for AZURE-NET are the host and mask for your Azure virtual network. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the /16 notation converts to a 255.255.0.0 subnet mask).
* The values in the brackets after nat must be the name of the internal, private network of your MacStadium private cloud, followed by the name of the outside interface of your Cisco ASA/ASAv device. By default, these are Private-1 and Outside, respectively.
* You can find the names of these networks in Appendix A of your IP Plan.
To resolve any of the listed common problems with the Cisco ASA/ASAv configuration, complete the following steps:
1. Clean up the firewall configuration.
* For more information, see Cleaning up the ASA/ASAv configuration.
2. Make the necessary changes to the configuration.
* For more information, see [Azure VPN Config for Cisco ASA/ASAv](/iaas/azure/azure-vpn-config-for-cisco-asaasav).
3. Re-run the complete configuration in Cisco ASDM-IDM.
* For more information, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
## There's traffic from Azure to MacStadium but you cannot access Azure from MacStadium
Sometimes, you might be able to establish an SSH connection from Azure to MacStadium but you might not be able to see or access Azure from MacStadium.
This might be due to Azure being configured to stop inbound traffic.
For information about how to enable inbound traffic, see [Azure Documentation: Filter inbound traffic with Azure Firewall DNAT using the Azure portal](https://docs.microsoft.com/en-us/azure/firewall/tutorial-firewall-dnat) and [Azure Documentation: Security groups](https://docs.microsoft.com/en-us/azure/virtual-network/security-overview).
## Troubleshooting
### Cleaning up the ASA/ASAv configuration
Sometimes, you might need to clean up the Cisco ASA/ASAv configuration and start over.
1. Verify that you are connected via VPN to your MacStadium private cloud.
For more information about how to connect to the VPN, see [Connecting to Your Cloud (via VPN)](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
3. For more information about how to log in to your firewall, see [Logging into Your Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
In the Cisco ASDM-IDM application toolbar, select **Tools > Command Line Interface**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line.
5. Run the following commands one by one, clicking Send in between. Replace the placeholders with their respective values. Use Table 1: Placeholders for reference.
```
clear configure tunnel-group { azure_virtual_network_gateway_ip }
clear configure crypto map azure-crypto-map
clear configure crypto ipsec ikev1 transform-set azure-ipsec-proposal-set
no nat ({ macstadium_network_name },{ macstadium_outside_interface }) 1 source static ONPREM-NET ONPREM-NET destination static AZURE-NET AZURE-NET
clear configure access-list AZURE-VPN-ACL
no object-group network AZURE-NET
no object-group network ONPREM-NET
```
### Table 1: Placeholders
| Placeholder | Description | Example |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `{ azure_virtual_network_gateway_ip }` | The public IP assigned to the virtual network gateway in Azure. | `192.168.0.0` |
| `{ macstadium_network_name }` | The name of the private network in MacStadium that needs to be accessed by Azure. You can find the information about your private network in Appendix A of the IP Plan. | `Private-1` |
| `{ macstadium_outside_interface }` | The name of the outside interface of your Cisco ASA/ASAv device. You can find the information about your outside interface in Appendix A of the IP Plan. | `Outside` |
## Additional Troubleshooting Resources by Microsoft
For more detailed troubleshooting instructions, see [Azure Documentation: Troubleshoot VPN Gateway](https://docs.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-troubleshoot).
## Additional Troubleshooting Resources by Cisco
For more detailed troubleshooting instructions, see [Cisco Documentation: IPsec Troubleshooting](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html).
# Azure VPN Config for Cisco ASA/ASAv
Source: https://docs.macstadium.com/iaas/azure/azure-vpn-config-for-cisco-asaasav
Configure your Cisco ASA/ASAv to complete an Azure-MacStadium VPN. A config template with placeholders for Azure and MacStadium network values is provided.
After you have created your site-to-site VPN connection in Microsoft Azure, you need to configure your Cisco firewall to recognize the connection and let traffic into your MacStadium private cloud.
You can use the configuration template provided below and fill in the missing information. You need to provide data from both Azure and MacStadium.
## Configuration template
Unless you have extensive experience with Azure and ASA/ASAv configurations, use the configuration from the template. Otherwise, your site-to-site VPN might not work as expected.
This is a template configuration that you can use to complete the configuration of your Azure-MacStadium site-to-site VPN connection.
```
! #1: Placeholders
!
! { azure_network_address } - The IP address of the virtual network in Azure that needs to have access to MacStadium.
! { azure_network_mask } - The subnet mask of the virtual network in Azure that needs to have access to MacStadium.
! { macstadium_network_address } - The IP address of the private network in MacStadium that needs to be accessed by Azure. By default, this is Private-1.
! { macstadium_network_mask } - The subnet mask of the private network in MacStadium that needs to be accessed by Azure. By default, this is Private-1.
! { macstadium_network_name } - The name of the private network in MacStadium that needs to be accessed by Azure. By default, this is Private-1.
! { macstadium_outside_interface } - The name of the outside interface of your Cisco ASA/ASAv device. By default, this is Outside.
! { azure_virtual_network_gateway_ip } - The public IP assigned to the virtual network gateway in Azure.
! { shared_key } - The IPSec pre-shared key used when creating the VPN connection in Azure.
!
! #2: NAT exemption
!
! The name "AZURE-NET" must be unique for the Cisco ASA/ASAv device.
object-group network AZURE-NET
description Azure Virtual Network
network-object { azure_network_address } { azure_network_mask }
! The name "ONPREM-NET" must be unique for the Cisco ASA/ASAv device.
object-group network ONPREM-NET
description OnPrem Network
network-object { macstadium_network_address } { macstadium_network_mask }
! The name "AZURE-VPN-ACL" must be unique for the Cisco ASA/ASAv device.
access-list AZURE-VPN-ACL extended permit ip object-group ONPREM-NET object-group AZURE-NET
nat ({ macstadium_network_name },{ macstadium_outside_interface }) 1 source static ONPREM-NET ONPREM-NET destination static AZURE-NET AZURE-NET
! #3: IKE configuration
crypto ikev1 enable { macstadium_outside_interface }
crypto ikev1 policy 5
authentication pre-share
encryption aes-256
hash sha
group 2
lifetime 28800
exit
crypto ipsec ikev1 transform-set azure-ipsec-proposal-set esp-aes-256 esp-sha-hmac
crypto ipsec security-association lifetime seconds 3600
crypto ipsec security-association lifetime kilobytes 102400000
tunnel-group { azure_virtual_network_gateway_ip } type ipsec-l2l
tunnel-group { azure_virtual_network_gateway_ip } ipsec-attribute
ikev1 pre-shared-key { shared_key }
! #4: IPSec configuration
! The name "azure-crypto-map" must be unique for the Cisco ASA/ASAv device.
crypto map azure-crypto-map 1 match address AZURE-VPN-ACL
crypto map azure-crypto-map 1 set peer { azure_virtual_network_gateway_ip }
crypto map azure-crypto-map 1 set ikev1 transform-set azure-ipsec-proposal-set
crypto map azure-crypto-map interface { macstadium_outside_interface }
sysopt connection tcpmss 1350
sysopt connection preserve-vpn-flows
```
## Fill in the configuration blanks
You need to manually replace the placeholders in the configuration template with the values for your Azure and MacStadium configurations.
### Get the configuration values
**\{ azure\_network\_address }**
This is the IP address of the virtual network in Azure that needs to have access to MacStadium.
1. Verify that you're logged into the Azure portal for your subscription.
2. In the search box at the top of the screen, type Virtual networks and select the respective entry in the filtered search results.\\
![Azure search results with Virtual networks entry highlighted]()
3. On the Virtual networks screen, select the virtual network used in your VPN.
4. In the network overview, look for the Address space. Use the IP address without the bit notation at the end (e.g. /16).\\
![Azure virtual network overview showing Address space field]()
**\{ azure\_network\_mask }**
This is the subnet mask of the virtual network in Azure that needs to have access to MacStadium.
1. Verify that you're logged into the Azure portal for your subscription.
2. In the search box at the top of the screen, type Virtual networks and select the respective entry in the filtered search results.\\
![Azure search results with Virtual networks entry highlighted]()
3. On the Virtual networks screen, select the virtual network used in your VPN.
4. In the network overview, look for the Address space. Use the bit notation at the end (e.g. /16) and convert it to a subnet mask. You can use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).\\
![Azure virtual network overview showing Address space in CIDR notation]()
**\{ macstadium\_network\_address }**
This is the IP address of the private network in MacStadium that needs to be accessed by Azure. By default, this is Private-1.
* You can find the information about your private network in Appendix A of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
**\{ macstadium\_network\_mask }**
This is the subnet mask of the private network in MacStadium that needs to be accessed by Azure. By default, this is Private-1.
**\{ macstadium\_network\_name }**\
This is the name of the private network in MacStadium that needs to be accessed by Azure. By default, this is Private-1.
**\{ macstadium\_outside\_interface }**
This is the name of the outside interface of your Cisco ASA/ASAv device. By default, this is Outside.
**\{ azure\_virtual\_network\_gateway\_ip }**
This is the public IP assigned to the virtual network gateway in Azure.
1. Verify that you're logged into the Azure portal for your subscription.
2. In the search box at the top of the screen, type Virtual network gateways and select the respective entry in the filtered search results.\\
![Azure search results with Virtual network gateways entry highlighted]()
3. On the Virtual network gateways screen, select the gateway for your VPN connection.
4. In the network overview, look for the Public IP address.\\
![Azure virtual network gateway overview showing Public IP address field]()
**\{ shared\_key }**
This is the IPSec pre-shared key used when creating the VPN connection in Azure.
* You must have this key saved separately.
## Complete the template
1. Copy the template into a text editing tool.
2. Replace all placeholders with their respective values.
3. Delete the remaining commented lines to clean up the template. Commented lines are indicated by ! at the beginning of the line.
4. Save your changes.
## Next steps
If you are ready to feed the complete configuration into your Cisco ASA/ASAv, see [Setting Up the MacStadium Side of the Site-to-Site VPN](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
# Site-to-Site VPN Configuration with Azure
Source: https://docs.macstadium.com/iaas/azure/site-to-site-vpn-configuration-with-azure
Configure an IPsec site-to-site VPN between Azure and the MacStadium Cisco ASA firewall. Covers Active/Standby and Active/Active modes with BGP routing.
## Overview
The goal of this documentation is to update the Site-to-Site VPN configuration between Azure and MacStadium ASA firewalls.
## Azure Networking Setup
To establish a stable and persistent connection between an Azure and the MacStadium private cloud, configure an IPsec Site-To-Site VPN between the two clouds.
Currently, for VPN connectivity between MacStadium and Azure there are two options:
* Active/Active Disabled. Every Azure VPN gateway consists of two instances in an Active/Standby configuration. According to Azure, for any planned maintenance or unplanned disruption that may happen to the Active instance, the Standby instance would take over (failover) automatically and resume the Site-To-Site VPN connections.
* Active/Active Enabled. In this mode, each Azure gateway instance has a unique public IP address and both instances establish an IPsec Site-To-Site VPN to your MacStadium firewall. For this VPN mode, you should also enable the TCP State Bypass feature in your ASA firewall which requires an access-list, class-map, policy-map, and a service-policy. This is a requirement for Site-To-Site VPNs with Virtual Tunnel Interfaces only and is configured to allow asynchronous routing between separate VPN tunnels.
In both VPN modes, static or dynamic routing with BGP is supported between MacStadium and Azure. In this document, BGP routing is used.
For more information about general Azure VPN design, see [Azure Documentation](https://learn.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-highlyavailable).
## Creating a Site-to-Site VPN
This is the general process for creating a Site-to-Site, from the Azure private cloud to the MacStadium private cloud.
1. Login to Azure.
2. Create a Virtual Network Gateway.
3. Create a Local Network Gateway.
4. Create a Site-to-Site VPN Connection.
## Log into Azure
1. Log into the Azure portal with the credentials.
2. Confirm the correct account and organization.
## Create a Virtual Network Gateway
The instructions below assume that there is a configured Azure Virtual Network.
In Azure, the virtual network gateway represents the Azure side of the Site-to-Site VPN tunnel.
1. In the search box at the top of the screen, type Virtual network gateways then select the respective entry in the filtered search results.\\
![Azure search results with Virtual network gateways entry highlighted]()
2. On the Virtual network gateways screen, click Create. (Or Create virtual network gateway, if this is the first gateway)
3. Select Subscription
4. Select Resource group
5. Provide a Name and select a Region
6. For Gateway type, confirm VPN is selected
7. For VPN type, confirm Route-based is selected
8. Select your SKU
* For more information about the available SKUs, see Azure Documentation: [Gateway SKUs](https://learn.microsoft.com/en-gb/azure/vpn-gateway/vpn-gateway-about-vpngateways).
9. Select the Virtual network to be used to send and receive traffic through the VPN.
10. For Public IP address, select an existing unused IP address or create a new one and provide a name for it.
11. In Availability zone, select Zone-redundant.
12. In the option Enable active-active mode, leave it as Disable for an Active/Standby VPN, or select Enabled for an Active/Active VPN mode.
* If Active/Active is enabled, then in the section SECOND PUBLIC IP ADDRESS select an existing unused public IP address or create a new one and provide a name for it.
* In Availability zone, select Zone-redundant
13. For the option Configure BGP, select Enabled.
14. In Autonomous system number (ASN) use the default value 65515 or, if required, use a different ASN in the private range of 64,512–65,534. This is used as the BGP process number in the MacStadium firewall.
15. In Custom Azure APIPA BGP IP address add an APIPA address from the range 169.254.21.X. Example 169.254.21.1. This IP will be used in the BGP configuration in your firewall.
16. Click Review + create, review the configuration.
17. Click Create, and wait for the deployment to complete.
* This might take several minutes.
18. Check if the virtual network gateway is deployed successfully.
* On the Virtual network gateways screen, select the virtual network gateway and click Properties.
* Verify that the Provisioning state is Succeeded.\\
![Azure virtual network gateway Properties showing Provisioning state Succeeded]()
* Example: Create a virtual network gateway\\
![Sample Azure virtual network gateway configuration form]()
* This image shows a sample configuration for a virtual network gateway.
## Create a Local Network Gateway
In Azure, the local network gateway represents the MacStadium side of the Site-to-Site VPN tunnel.
1. In the search box at the top of the screen, type Local network gateways and select the respective entry in the filtered search results. Azure filters results.\\
![Azure search results with Local network gateways entry highlighted]()
2. On the Local network gateways screen, click + Create.
3. Provide a Name.
4. For IP Address, provide the IP address of the public network listed in Appendix B of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* By default, this is the FW1-Outside network.
5. Leave Address space empty and click Next : Advanced.
6. Set the option Configure BGP settings to Yes.
7. Enter the private ASN number to use, for instance 65516.
* Notice that ASNs 8075, 8076, 12076 (public), 65515, 65517, 65518, 65519, 65520 (private) are reserved by Azure and cannot be used.
8. In BGP peer IP address enter the APIPA IP address used in the Azure side, for example 169.254.21.2.
9. Click Review + create and then Create.
10. Wait for the deployment to complete.
* This might take several minutes. When the deployment is complete, the local network gateway becomes listed under All resources.
## Create the VPN Connection
After the virtual network gateway and a local network gateway are in place, create and configure the VPN connection between Azure and the MacStadium private cloud.
1. In the search box at the top of the screen, type Virtual network gateways and select the respective entry in the filtered search results. Azure filters results.
2. On the Local network gateways screen, select the local network gateway created earlier.
3. From the sidebar menu, select Connections and click + Add.\\
![Azure local network gateway Connections panel with Add button]()
4. Provide a Name.
5. Set the Connection type to Site-to-Site (IPsec).\\
![Azure Create Connection form with Site-to-Site IPsec connection type selected]()
6. Select the correct Region and click Next : Settings.
7. Select the Virtual network gateway and Local network gateway that were previously created.
8. For Shared key (PSK), provide an IPSec pre-shared key.
* Keep a record of the pre-shared key. It will be used later.
9. For IKE Protocol, confirm IKEv2 is selected.
10. Select Enable BGP.
11. Select Enable Custom BGP Addresses.
12. In the Primary Custom BGP Address field, select the APIPA address that were created before.
13. In IPsec / IKE policy, select Custom
14. Set IKE Phase 1 and IKE Phase 2 as follows:\\
![Azure IPsec IKE policy settings for IKE Phase 1 and Phase 2]()
15. Review the remaining pre-filled setting and click Review + Create.\
![Azure Create Connection review page before final creation]()
\\
![Azure VPN connection settings summary before creation]()
16. Click Create at the next step.
17. Wait for the operation to be completed.
* This might take a while. When the deployment is complete, click Go to resource\\
![Azure deployment complete screen with Go to resource button]()
18. In the Overview page, select Download configuration:\\
![Azure VPN connection Overview page with Download configuration option]()
19. In the pop-up window, set Device vendor to Cisco, Device family to ASA (Adaptive Security Appliance) and Firmware version to CiscoASA\[9.8+\_ONLY]\_RouteBased(IKEv2>VTI+BGP) and click Download configuration.\\
![Download configuration dialog with Cisco ASA and firmware version selected]()
* The status of the newly created connection is Unknown.
### Ensure that Azure Allows Inbound Traffic
Based on the requirements and current setup, it might be necessary to enable inbound traffic from MacStadium to Azure.
For more information, see Azure Documentation: [Filter inbound Internet traffic with Azure Firewall DNAT using the Azure portal](https://learn.microsoft.com/en-us/azure/firewall/tutorial-firewall-dnat) and [Network security groups](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview).
To proceed with the MacStadium side of the configuration, see Azure [VPN Config for Cisco ASA/ASAv](/iaas/azure/azure-vpn-config-for-cisco-asaasav).
After creating the Site-to-Site VPN connection, configure the Cisco firewall to recognize the connection and let traffic into the MacStadium private cloud. Make sure to download the VPN configuration template from Azure.
## Configuration Template
Without extensive experience with Azure and ASA/ASAv configurations, it is recommended to use a configuration template. Otherwise, the Site-to-Site VPN might not perform as expected.
1. In the VPN configuration script downloaded from Azure, the configuration starts after the section below:\\
![Azure VPN configuration script header section showing where configuration begins]()
2. Find the section where the BGP configuration starts.
3. Add the MacStadium private network and mask.
```
router bgp 65516
bgp log-neighbor-changes
bgp graceful-restart
bgp router-id 169.254.21.1
address-family ipv4 unicast
neighbor 10.0.1.254 remote-as 65515 neighbor 10.0.1.254 ebgp-multihop 255 neighbor 10.0.1.254 activate
! NOTE: THE LOCAL NETWORKS TO BE ADDED STATICALLY TO THIS BGP ROUTER NEED TO GO HERE BELOW:
! NOTE: You can add more local on-premises network ranges statically here as well, using the "network" command just like above.
!etc...
! network 10.221.188.0 mask 255.255.254.0
no auto-summary no synchronization exit-address-family
```
* Find the MacStadium Private Network by checking that section in Appendix A of the IP Plan.
* Make sure the name of the interface being used for the VPN connection is Outside as this is the name of the interface in the script downloaded from Azure. If there is a different interface name for the VPN, then make sure to replace all sections where the Outside interface is referenced in the script by the actual interface name being used.
* **Warning:** Ignore the section, STATIC ROUTING SETUP FOR AZURE, and do not configure any static routes, as BGP will be used instead.
4. Access the firewall through SSH using the credentials available in the IP Plan.
5. Paste the ASA configuration script and confirm all commands were accepted.
6. Use the following commands to confirm if the VPN has been successfully established:
```
show vpn-sessiondb l2l show crypto ipsec sa
```
* For more information, see: [Cisco Secure Firewall ASA Series Command Reference, S Commands](https://www.cisco.com/c/en/us/td/docs/security/asa/asa-cli-reference/S/asa-command-ref-S/show-cr-to-show-cz-commands.html).
7. Save the configuration with the ASA CLI command: write memory.
* Access to the Azure environment from the MacStadium host is now possible (and vice-versa).
* To feed the complete configuration into your Cisco ASA/ASAv, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
# Verify your Azure-to-MacStadium VPN connection
Source: https://docs.macstadium.com/iaas/azure/verify-azure
Verify your Azure-MacStadium site-to-site VPN tunnel using the Cisco ASDM-IDM CLI. Checks ISAKMP security associations to confirm the tunnel is active.
After you have completed both the Microsoft Azure and the MacStadium sides of the configuration, you might want to verify that the tunnel is working as expected.
1. Verify that you are connected via VPN to your MacStadium private cloud.
* For more information about how to connect to the VPN, see [Connecting to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
* For more information about how to log in to your firewall, see [Logging into Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
3. In the Cisco ASDM-IDM application toolbar, select **Tools > Command Line Interface**.\\
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line, enter the following command, and click **Send**.
```
show crypto isakmp sa
```
If the site-to-site VPN connection is configured properly, you should see information about an active IKEv1.
For more information about this verification command, see [Cisco Documentation: show crypto isakmp sa](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#isakmp_sa).
## Verify that there is an IPsec security association between peers
1. Verify that you are connected via VPN to your MacStadium private cloud.
* For more information about how to connect to the VPN, see [Connecting to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
* For more information about how to log in to your firewall, see [Logging into Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
3. In the Cisco ASDM-IDM application toolbar, select Tools > Command Line Interface\\
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line, enter the following command, and click Send.
```
show crypto ipsec sa
```
If the site-to-site VPN connection is configured properly, you should see a detailed log.
For more information about this verification command, see [Cisco Documentation: show crypto ipsec sa](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#ipsec_sa).
## Verify that the tunnel is connected
1. Log in to your Azure portal.
2. On the All resources page, find the connection that represents your VPN connection (for example: macstadium-vpn) and click it.
3. Select Overview and check the Status of the connection. When your tunnel is properly connected, the status is: Connected.\\
![Azure VPN connection overview showing Connected status]()
## Test traffic and visibility through the tunnel
1. Verify that you have created a virtual machine in MacStadium.
2. Verify that you have created a virtual machine in Azure.
3. In the terminal on your MacStadium VM, run the following command.
* Replace `` with the username for your Azure VM.
* Replace `` with the private IP of the Azure VM.
```
ssh @
```
4. When prompted, provide your password or key for the specified username on the specified Azure VM.
* If the connection is successful, the prefix of the terminal becomes ``@``. This indicates that you have connected from MacStadium to Azure over the tunnel.
5. Run the following command.
* Replace `` with the username for your MacStadium VM.
* Replace `` with the private IP of the MacStadium VM.
```
ssh @
```
6. When prompted, provide your password or key for the specified username on the specified MacStadium VM. If the connection is successful, the prefix of the terminal becomes ``@``. This indicates that you have connected from Azure to MacStadium over the tunnel.
## Troubleshooting
See our [Azure Troubleshooting](/iaas/azure/azure-troubleshooting) doc for some common issues with Azure-MacStadium Site-to-Site VPN Connections.
# Disabling Activation Lock and Find My on Mac
Source: https://docs.macstadium.com/iaas/bare-metal-macs/2018-mac-mini-deactivation-process
Turn off Find My, remove Activation Lock, and sign out of your Apple Account before returning a rented Mac to MacStadium. Required to avoid extra charges.
Before MacStadium can reclaim your rented Mac, you must disable Activation Lock by turning off Find My and signing out of your Apple Account. If this is not done, MacStadium engineers cannot reclaim the machine, and charges may apply.
## Turn Off Find My
1. Open **Apple menu** > **System Settings**.
2. Click your name at the top of the sidebar, then click **iCloud**.
3. Click **See All**, then click **Find My Mac**.
4. Click the toggle to turn it off.
5. Enter your Apple Account password when prompted.
## Sign Out of Your Apple Account
1. Open **Apple menu** > **System Settings**.
2. Click your name at the top of the sidebar.
3. Scroll down and click **Sign Out**.
## If You No Longer Have Access to the Mac
You can remove Activation Lock remotely:
1. Sign in to [iCloud.com](https://www.icloud.com) and open **Find My**.
2. Select **All Devices**, then select your Mac.
3. Click **Remove from Account**.
You can also do this from the **Find My** app on another Apple device signed in with the same Apple Account.
For more details, see Apple's official documentation on [Activation Lock for Mac](https://support.apple.com/en-us/102541).
# Common macOS CI/CD tools for MacStadium
Source: https://docs.macstadium.com/iaas/bare-metal-macs/common-tools
Essential tools for macOS CI/CD on MacStadium: Xcode via Xcodes.app or direct download, Homebrew, fastlane, CocoaPods, and Apple ID setup best practices.
These tools enable the provisioning and use of hosted Mac resources for Apple platform development.
# Xcode
Xcode is the Apple IDE, enabling the development of applications for Apple platforms, including iOS and macOS. In order to download Xcode, a valid Apple ID is required, regardless of the method used. There are several ways to install it:
## Xcodes.app (Recommended)
The Xcodes app is the fastest and easiest way to install Xcode. By leveraging multithreaded downloads, as well as accelerated decompression of Xcode packages, Xcodes is much faster than directly downloading from the Apple Developer Portal or using the App Store, while still using signed official packages from Apple. Additionally, while it does require an Apple ID, it does not sign the Mac into iCloud, which prevents issues with Find My Mac.
## Installation
Download the latest version of Xcodes from the following link:
[https://github.com/XcodesOrg/XcodesApp/releases/latest](https://github.com/XcodesOrg/XcodesApp/releases/latest)
Once downloaded, drag Xcodes.app to the Applications folder to install the app.
Alternatively, if Homebrew is installed, then run the following command in Terminal:
```text theme={null}
brew install --cask xcodes
```
## Usage
Once Xcodes is installed, launch the app from the Applications folder. Xcodes displays all of the available releases of Xcode. In order to download and install a release, authentication with an Apple ID is required. To do this, click the Account icon in the upper right corner of the app:
![Xcodes app main window showing Account icon in the upper right corner]()
### Recommended: Enable experimental unxip
The decompression (unxip) process for Xcode is typically quite lengthy. To help accommodate this, Xcodes has an experimental decompression method that speeds things up. In our testing, this has been shown to be both stable and effective. To enable this, navigate to Xcodes>Settings>Experiments in the menu bar, and then check "When unxipping, use experiment":
![Xcodes Settings Experiments panel with experimental unxip option checked]()
Once authenticated, Xcode and individual platform SDKs may be downloaded and installed by clicking the Install button next to the desired release. During installation, Xcodes may prompt for elevated access; if so, then enter a username/password to allow this.
## Download from Apple's Developer Portal (Recommended)
Xcode may also be downloaded directly from Apple using a web browser. While slower than Xcodes, this method may be preferred if there are concerns around third-party software:
[https://developer.apple.com/download/all/?q=Xcode](https://developer.apple.com/download/all/?q=Xcode)
As with other methods, it is necessary to sign in with an Apple ID to download and install the software. Once downloaded, double-click the xip file to extract Xcode, then copy to the Applications folder to install.
## Download from the App Store (Not Recommended)
Xcode is officially distributed by Apple via the App Store. To install Xcode this way, visit the following link:
[https://apps.apple.com/us/app/xcode/id497799835?mt=12](https://apps.apple.com/us/app/xcode/id497799835?mt=12/)
This method is not recommended, as it requires binding the Mac to an Apple ID, which may inadvertently enable iCloud/Find My Mac. Machines with Find My Mac enabled are Activation Locked, and cannot be used by other users until the machine is unlocked by the original account. As a result, machines returned with Find My Mac enabled are subject to recovery fees.
# Homebrew
Homebrew is a package manager that makes installing packages from the Mac terminal quick and easy. It is generally the preferred method used to install system utilities and libraries.
### Prerequisites
Homebrew relies upon Xcode Command Line Tools, so Xcode must be installed. To install it via the Command Line Tools by entering the following command into Terminal:
```text theme={null}
xcode-select --install
```
Once this command is run, a system prompt appears offering to install the Xcode Command Line Tools. Click Install and wait for the installation to finish before proceeding.
The Mac Terminal App is located in the Utilities Folder under the Applications Folder, and allows for access to the system shell, which is zsh by default.
### Process
Once prerequisites are installed, installing Homebrew can be done with a single line of code in the Terminal.
1. Open your Terminal App.
2. Copy and paste the following command, and then press ENTER.
```text theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
3. Hit the RETURN key when prompted.
4. Follow the installation process on screen.
Update Homebrew when necessary, by using the following command in the Terminal App:
```text theme={null}
brew update
```
Enable auto completion by entering the command:
```text theme={null}
brew install bash-completion
```
### Uninstalling Homebrew
1. Open the Terminal App.
2. Copy and paste the following command and then press ENTER:
```text theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"
```
# Ansible
[Installation Guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
[Ansible Docs](https://docs.ansible.com/ansible/latest/index.html)
Ansible is a largely free and open source server configuration tool. It must be installed, along with Python, on the control machine, which might be the local desktop. From there, Ansible requires SSH access to the target server -- in this case the Mac Cloud.
Once Ansible has gained access to the target environment via SSH, it can run provisioning scripts and the like to prepare the environment for whatever work needs to be done -- be it CI or anything else.
## Starter Scripts
MacStadium maintains a handful of example scripts to get started.
## Ansible Roles
Roles are sets of tasks and files used to configure a host machine to perform a specific role (thus, the name).
[Ansible Role: macOS CI](https://github.com/macstadium/ansible-role-osx-ci)
[Ansible Role: Xcode](https://github.com/macstadium/ansible-role-xcode)
## Ansible Playbooks
Playbooks are mappings of Ansible Roles and the various host machines they are meant to configure for a given process.
[Ansible Playbook: macOS CI Setup](https://github.com/macstadium/ansible-playbook-osx-ci-setup)
# Packer
[Installation Guide](https://www.packer.io/intro/getting-started/install.html)
[Packer Docs](https://www.packer.io/docs/index.html)\
Packer is an open-source tool that stores a live image of a virtual machine, which can be cloned in seconds, rather than minutes or hours. It uses JSON to define the VM template, and because it is command-line-driven, it can easily be integrated into the build pipeline.
Packer is not a direct substitute for provisioning solutions. In fact, it is built to interface easily with Chef, Puppet, and Ansible for the provisioning of the base VM image.
# Connecting to your Mac for the first time
Source: https://docs.macstadium.com/iaas/bare-metal-macs/connecting-to-your-mac-for-the-first-time
Just got your MacStadium installation ticket? Connect via macOS Screen Sharing, a VNC client, or SSH using the credentials from your ticket.
All Mac mini subscriptions are pre-configured to connect using the following methods:
**macOS Screen Sharing**: Open Safari and type `vnc://` (replacing the IP address with one provided in your install ticket) OR enter the IP address into the Screen Sharing app for remote access.
**VNC**: The Apple Screen Sharing server also supports VNC connections using your client of choice, such as TigerVNC. This allows for remote desktop access from other OSes, albeit with reduced performance.
**SSH Terminal**: Use your OS’s built in terminal to gain console access to the server.
# Bare metal Mac configurations
Source: https://docs.macstadium.com/iaas/bare-metal-macs/mac-mini-comparison-chart
Side-by-side specs for all MacStadium bare metal Mac configurations: Mac mini and Mac Studio, with chip, RAM, storage, and recommended use case.
MacStadium offers bare metal Mac hardware in two product lines. Use the tables below to compare configurations and find the right fit for your workload. For benchmark scores, see the [benchmarks page](/iaas/bare-metal-macs/macstadium-bare-metal-mac-benchmarks).
## Mac mini
Mac mini is recommended for most CI/CD and Orka workloads. Standard configurations are available for immediate purchase on the [MacStadium customer portal](https://portal.macstadium.com/register).
| Plan | Chip | CPU cores | RAM | SSD | Best for |
| ----- | ------ | --------- | ----- | ------ | ------------------------------------------- |
| M2.S | M2 | 8 | 8 GB | 256 GB | VDI, light CI/CD, basic automation |
| M4.S | M4 | 10 | 16 GB | 256 GB | VDI, light CI/CD, basic automation |
| M1.M | M1 | 8 | 16 GB | 1 TB | VDI, CI/CD, remote development |
| M2.M | M2 | 8 | 16 GB | 1 TB | VDI, CI/CD, Orka nodes |
| M4.M | M4 | 10 | 24 GB | 512 GB | VDI, CI/CD, Orka clusters |
| M2.L | M2 Pro | 10 | 16 GB | 1 TB | CI/CD, Orka nodes |
| M4.L | M4 Pro | 12 | 48 GB | 1 TB | Multi-VM CI/CD, Orka clusters |
| M2.XL | M2 Pro | 12 | 32 GB | 2 TB | CI/CD pipelines, Orka clusters |
| M4.XL | M4 Pro | 14 | 64 GB | 2 TB | High-concurrency CI/CD, large Orka clusters |
All Mac mini configurations are Apple silicon (ARM). Intel Mac mini hardware is available for custom orders. [Contact MacStadium sales](https://www.macstadium.com/contact/sales) for more.
**For Orka clusters:** Medium and larger configurations (M2.M and above) are recommended. More RAM means more concurrent VMs per node. M2.XL and above are the best fit for teams running multiple VMs simultaneously.
## Mac Studio
Mac Studio is recommended for GPU-intensive workloads: video rendering, AI/ML inference, and running local language models. If your use case requires serving a model on-device rather than calling an external API, Mac Studio is the right tier. Standard configurations are available for immediate purchase on the [MacStadium customer portal](https://portal.macstadium.com/register).
| Plan | Chip | CPU cores | RAM | SSD | Best for |
| ---- | -------- | --------- | ------ | ---- | ----------------------------------------------------------------- |
| S1.M | M1 Max | 10 | 64 GB | 2 TB | GPU workloads, AI/ML inference, video rendering |
| S2.M | M2 Ultra | 24 | 64 GB | 2 TB | High-throughput GPU, local LLM serving, on-device model inference |
| S2.L | M2 Ultra | 24 | 128 GB | 2 TB | Very large local models, maximum memory GPU workloads |
## Related
* [MacStadium Bare Metal Mac Benchmarks](/iaas/bare-metal-macs/macstadium-bare-metal-mac-benchmarks)
* [Data center locations](/iaas/iaas-overview/data-center-locations)
* [Common tools](/iaas/bare-metal-macs/common-tools)
# MacStadium Bare Metal Mac Benchmarks
Source: https://docs.macstadium.com/iaas/bare-metal-macs/macstadium-bare-metal-mac-benchmarks
Benchmark results for MacStadium bare metal Mac hosts: Xcode, Geekbench 6, and Cinebench R24 scores with multipliers to help choose the right Mac for CI/CD.
## About
MacStadium offers a wide selection of Bare Metal Mac hosts for a variety of applications.\
When selecting host machine varieties, most MacStadium customers seek to strike a balance between the volume of computation that they need to do, the speed at which a given job (like a CI build) should be completed, and the cost involved.
## Overview
**Benchmarking**
When evaluating Macs, the goal is to determine the optimal performance of a given piece of Mac hardware, including CPU performance, GPU performance, and real-world performance for CI/CD applications. To achieve this, refer to these synthetic benchmarks:
* XcodeBenchmark
* Geekbench 6 Multi-core
* Geekbench 6 Compute
* Cinebench R24
[Read the blog post for a complete description of the benchmarking process](https://www.macstadium.com/blog/choosing-your-mac-with-macstadiums-benchmarks)
**Benchmark Results**
The standard models table reflects tests performed on macOS 15.1 with Xcode 16.1 and Cinebench R24. The full results table reflects the original benchmark run on macOS 13.4.1 with Cinebench R23 and is included for reference.
## Benchmarking Baseline
This machine is used as the baseline when referencing multipliers. In other words, a machine with a multiplier of 1.4x is 40% more performant than the baseline machine for the specified test. Multipliers are shown below the raw score in each cell.
| Name | CPU | Xcode | GB6 CPU | GB6 GPU | CB R24 | RAM | SSD | Mac Model |
| ---- | ---------- | -------------------- | ------------------ | ------------------ | ------------------- | ---- | --- | --------- |
| M2.M | M2
8C | 190.33s
(1.00x) | 10244
(1.00x) | 48348
(1.00x) | 600.07
(1.00x) | 16GB | 1TB | Mac mini |
## Current standard models
This table includes Standard models currently available as Bare Metal from MacStadium.
| Name | CPU | Xcode | GB6 CPU | GB6 GPU | CB R24 | RAM | SSD | Mac Model |
| ----- | ----------------- | -------------------- | ------------------ | ------------------- | -------------------- | ----- | ----- | ---------- |
| S2.L | M2 Ultra
24C | 98.043s
(1.94x) | 21734
(2.12x) | 215160
(4.45x) | 1975.14
(3.29x) | 128GB | 2TB | Mac Studio |
| S2.M | M2 Ultra
24C | 96.82s
(1.97x) | 21777
(2.13x) | 218001
(4.51x) | 1981.3
(3.30x) | 64GB | 2TB | Mac Studio |
| M4.XL | M4 Pro
14C | 97.05s
(1.96x) | 22582
(2.20x) | 113953
(2.36x) | 1639.38
(2.73x) | 64GB | 2TB | Mac mini |
| M4.L | M4 Pro
12C | 107.28s
(1.77x) | 20769
(2.03x) | 100559
(2.08x) | 1478.15
(2.46x) | 48GB | 1TB | Mac mini |
| M4.M | M4
10C | 139.14s
(1.37x) | 15123
(1.48x) | 58437
(1.21x) | 982.56
(1.64x) | 24GB | 512GB | Mac mini |
| M4.S | M4
10C | 138.95s
(1.37x) | 15153
(1.48x) | 58309
(1.21x) | 983.99
(1.64x) | 16GB | 256GB | Mac mini |
| S1.M | M1 Max
10C | 146.91s
(1.30x) | 13049
(1.27x) | 123103
(2.55x) | 858.57
(1.43x) | 64GB | 2TB | Mac Studio |
| M2.XL | M2 Pro
12C | 128.11s
(1.49x) | 14951
(1.46x) | 86500
(1.79x) | 1047.68
(1.75x) | 32GB | 2TB | Mac mini |
| M2.L | M2 Pro
10C | 147.16s
(1.29x) | 13076
(1.28x) | 78215
(1.62x) | 817.66
(1.36x) | 16GB | 1TB | Mac mini |
| M2.M | M2
8C | 190.33s
(1.00x) | 10244
(1.00x) | 48348
(1.00x) | 600.07
(1.00x) | 16GB | 1TB | Mac mini |
| M2.S | M2
8C | 190.33s
(1.00x) | 10205
(1.00x) | 48229
(1.00x) | 605.38
(1.01x) | 8GB | 256GB | Mac mini |
## Full Results
This table includes the full range of benchmarked hardware, including several machines not currently available for reference. Current and former MacStadium standard bare metal machines will have their name listed.
| Name | CPU | Xcode | GB6 CPU | GB6 GPU | CB R23 | RAM | SSD | Mac Model |
| ----- | ----------------- | --------------------- | ------------------ | ------------------- | ------------------ | ----- | ----- | ---------- |
| S2.M | M2 Ultra
24C | 53.599s
(2.31x) | 20963
(2.38x) | 206071
(6.09x) | 28945
(3.68x) | 64GB | 2TB | Mac Studio |
| S1.L | M1 Ultra
20C | 65.558s
(1.89x) | 18060
(2.05x) | 174505
(5.16x) | 24214
(3.08x) | 128GB | 4TB | Mac Studio |
| N/A | M2 Max
12C | 74.003s
(1.67x) | 14872
(1.69x) | 127390
(3.76x) | 14885
(1.89x) | 32GB | 512GB | Mac Studio |
| M2.XL | M2 Pro
12C | 74.659s
(1.64x) | 14686
(1.67x) | 81837
(2.42x) | 14812
(1.88x) | 32GB | 2TB | Mac mini |
| S1.M | M1 Max
10C | 89.340
(1.39x) | 12947
(1.47x) | 119490
(3.53x) | 12457
(1.58x) | 64GB | 2TB | Mac Studio |
| M2.L | M2 Pro
10C | 84.904s
(1.46x) | 12405
(1.41x) | 73622
(2.18x) | 11858
(1.51x) | 16GB | 1TB | Mac mini |
| M2.M | M2
8C | 106.259s
(1.17x) | 10130
(1.15x) | 45902
(1.36x) | 8776
(1.12x) | 16GB | 1TB | Mac mini |
| M2.S | M2
8C | 108.477s
(1.14x) | 10192
(1.16x) | 45891
(1.36x) | 8780
(1.12x) | 8GB | 256GB | Mac mini |
| M1.M | M1
8C | 123.885s
(1.00x) | 8818
(1.00x) | 33843
(1.00x) | 7869
(1.00x) | 16GB | 1TB | Mac mini |
# Allowing Specific IPs to Access MacStadium via Internet
Source: https://docs.macstadium.com/iaas/cisco-firewalls/allowing-specific-ips-to-access-macstadium-via-internet
Configure Static NAT and ACL rules on a Cisco ASA firewall to allow specific external IP addresses to access MacStadium hosts on the private network.
## Overview
Static Network Address Translation (NAT) is used to conserve IP addresses. It allows private IP networks with unregistered IP addresses to connect to the Internet. NAT translates the private (not globally unique) addresses in the internal network into legal addresses before they are forwarded to another network.
Think of NAT as a one-to-one mapping of private IP addresses to public IP addresses. It allows mapping of an IP address on the internal network to an IP address that you want to make public.
Once that mapping is set, then there are a list of rules that are needed to grant or deny access, which is called an Access Control List (ACL). The ACL is a list of rules that specifies which users or systems are granted or denied access to a particular object. ACLs are also installed in routers or switches, where they act as filters, managing which traffic can access the network.
This document describes how to configure a Static Network Address Translation (NAT) and Access Control List (ACL) on a Cisco ASA Firewall to allow external IP addresses to access the MacStadium hosts.
## Prerequisites
Cisco AnyConnect Client: Connect to the VPN using Cisco AnyConnect Client, then access the firewall via SSH or Cisco ASDM.
## Considerations
In this document, the source IP address is the public IP that needs to be whitelisted in the firewall. The destination hosts are the MacStadium servers behind the firewall Private interface.
This document demonstrates how to allow TCP port 443 (HTTPS) in the Cisco Adaptive Security Appliance (ASA) firewall from an external IP address to the subnet 10.221.188.0/23 configured in the Private-1 interface as an example.
The example source IP address **76.76.21.241** is used in this document.
## Install Options
Updating the Cisco Adaptive Security Appliance (ASA) can be done two different ways:
**Via Command Line Interface (CLI)**
Using a CLI allows you to write script changes in a notepad and have those changes reviewed by someone before running them. This method is good for writing scripts.
**Via Cisco Adaptive Security Device Manager (ASDM)**
Using an ASDM allows you to make line-by-line changes, while using a graphical user interface (GUI).
## Configuring Static Network Address Translation (NAT)
**NAT via Command Line Interface (CLI)**
1. Connect to the firewall via SSH using MacStadium credentials that are available in the IP Plan.
2. When the > prompt appears, type enable
3. Enter the password again.
* It should look like this:
```
ciscoasa>
ciscoasa>enable
ciscoasa>****
ciscoasa#
```
* The privileged mode appears, as indicated by the # prompt.
4. Enter the configuration mode and create an object and static NAT rule for that host:
```
ciscoasa#configure terminal
ciscoasa(config)#object network Example-Host-31
ciscoasa(config-network-object)#host 10.221.188.31
ciscoasa(config-network-object)#nat (Private-1,Outside) static 207.254.16.239
ciscoasa(config-network-object)#end
ciscoasa#write memory
```
Replace the example MacStadium NAT IP address (207.254.16.239) with an available Public IP listed in the MacStadium IP Plan.
## NAT via Cisco Adaptive Security Device Manager (ASDM)
1. Connect to the ASDM using the MacStadium credentials from your IP Plan.
2. Navigate to Configuration > Firewall > NAT Rules > +Add > Add NAT Rule.\\
![ASDM NAT Rules with Add NAT Rule option selected]()
3. Give the Object representing the internal MacStadium host a name (Example-Host-31).
4. Confirm the Type is set as Host.
5. In IP address enter the private IP address of the host (consult your IP Plan).
6. In the NAT section, confirm Static is selected and enter the MacStadium Public IP address to assign the host.
7. Click Advanced and set the Source Interface to Private-1 and Destination Interface to Outside.
8. Confirm the Protocol is set to tcp.
9. Click OK > OK > Apply.\\
![ASDM Add NAT Rule dialog with static NAT and interface settings completed]()
10. Click Save
11. Click Apply Changes\\
![ASDM Apply Changes confirmation dialog]()
## Configuring Access Control Lists (ACLs)
### ACL via Command Line Interface (CLI)
For external access to MacStadium hosts, a static NAT must be previously configured.
This guide assumes that the `Private-1-IPs` object has been configured in the firewall.
1. Confirm that `Private-1-IPs` was configured by running the following CLI command:\
`ciscoasa#show running-config object id Private-1-IPs`
2. If `Private-1-IPs` has not been configured, then use the following commands to create it:
```
ciscoasa#configure terminal
ciscoasa(config)#object network Private-1-IPs
ciscoasa(config-network-object)#subnet 10.221.188.0 255.255.254.0
```
3. Connect to the firewall via SSH and from the command line enter the MacStadium credentials that are available in your [IP Plan](/macstadium/macstadium-overview/ip-plan)
4. Confirm the privileged mode is enabled (indicated by the # prompt).
5. Enter the configuration mode and create an Object representing the source IP address.
6. Replace EXAMPLE with a name to use to identify the object and the source Public IP address (**76.76.21.241**) with the source IP address to whitelist on the firewall.
```
ciscoasa#configure terminal
ciscoasa(config)#object network EXAMPLE
ciscoasa(config-network-object)#host 76.76.21.241
```
7. Create an Access Control List to allow traffic through the Cisco ASA firewall. From the configuration mode enter the following access-list command:
```
ciscoasa(config)#access-list Outside_access_in line 1 extended permit tcp object EXAMPLE object Private-1-IPs eq https
```
To allow access to a single internal host instead of the entire Private-1 network, reference the object you created for that specific host. Example: `ciscoasa(config)#access-list Outside_access_in line 1 extended permit tcp object EXAMPLE object Example-Host-31 eq https`
8. Apply the new access-list to the Outside interface:
```
ciscoasa(config)#access-group Outside_access_in in interface Outside
```
The command above only needs to be entered the first time the ACL is configured.
9. Exit and save the configuration:
```
ciscoasa(config)#end
ciscoasa(config)#write memory
```
Instead of creating an object representing a single source IP address, you can create a Network Object Group and add Network Objects to it. This is useful if you expect to allow more IP addresses in the future. For more information, see:
[Cisco ASA 9.6 Access Objects Guide](https://www.cisco.com/c/en/us/td/docs/security/asa/asa96/configuration/firewall/asa-96-firewall-config/access-objects.html)
## ACL via Cisco Adaptive Security Device Manager (ASDM)
For external access to your MacStadium hosts, a static NAT must be previously configured.
1. Connect to the firewall through ASDM using the MacStadium credentials that are available in your IP Plan.
2. Navigate to: Configuration > Firewall.
3. Click +Add and select Network Object on the right menu.
4. Give the object a name.
5. Confirm its type is set to Host.
6. Enter the source IP address and optionally a description.\\
![ASDM Add Network Object dialog with source IP address and host type fields]()
7. Click OK.
8. In the Access Rules section, confirm the Outside interface is selected. If rules are applied to the Outside interface, select the first rule from the top.\\
![ASDM Access Rules with Outside interface selected]()
9. Click +Add and select Add Access Rule.
10. Confirm the Outside interface is selected, and the Action is set to Permit.
11. Select the object host (or group) that was just created as the Source.
12. Select the Private-1-IPs object as the Destination.
13. In Service type the protocol/ports to be allowed (in this example tcp/https).
14. Click OK.\\
![ASDM Add Access Rule dialog with Outside interface, source object, and service fields]()
To allow access to a single internal host instead of the entire Private-1 network, reference the object created for that specific host in the Destination field.
15. Make sure the new rule is at the TOP. To move the new rule to the top, select the new rule and click the upper arrow highlighted.
![ASDM Access Rules list with new rule selected and move-to-top arrow highlighted]()
16. Click Apply
17. Click Save
18. Click Apply Changes
# Backup and Restore Firewall Config using ASDM
Source: https://docs.macstadium.com/iaas/cisco-firewalls/backup-and-restore-firewall-config-using-asdm
This process outlines how to backup and restore a configuration by executing line by line changes, while using a graphical user interface.
## Overview
This process outlines how to backup and restore a configuration by executing line by line changes, while using a graphical user interface.
The backup files are stored on a local system as a ZIP file.
It is important to store this ZIP file in an easily accessible place in case of an emergency. Plan a backup to be taken anytime changes are made to the firewall configuration.
If the firewall configuration is in a high-availability (HA) Pair, then ensure that the backup and restore to the Active firewall is enabled. This can be verified on the Cisco Adaptive Security Device Manager (ASDM) Dashboard, under the **Failover Status** field. Look for **Primary (Active)**. If this is not enabled, then login to the other firewall to perform these steps.
## Prerequisites
* Access to MacStadium firewall
* MacStadium login information
* The ability to login to the firewall using the Cisco Adaptive Security Device Manager (ASDM) firewall software
If a passphrase was set on the backup, then it needs to be available during the restore process.
## Backup Process
1. Establish a VPN connection to the MacStadium environment.
2. Connect to the firewall using the Cisco Adaptive Security Device Manager (ASDM).
3. Click the Tools menu, located at the top of the ASDM application and then select Backup Configuration.\\
![ASDM Tools menu with Backup Configuration option highlighted]()
4. Select a location to place the backup files.
5. Enter a name for the backup file.\\
![ASDM Backup Configuration dialog with file name and location fields]()
6. The system shows the local file structure. Select an appropriate place and name for your backup.\\
![Local file browser for selecting backup file save location]()
7. Click Select File.
8. Accept the defaults of Backup All.
9. Click Backup.\\
![ASDM Backup Configuration dialog with Backup All option and Backup button]()
**Optional:** If the firewall is configured with identity certificates, then select a passphrase to encrypt identity certificates. Document the passphrase that is used as it is needed for future restores.
![ASDM passphrase field for encrypting identity certificates in backup]()
10. Click OK
The Progress Message can be copied to a text editor for review and validation.
11. Click Close after backup is completed. A Backup Statistics window opens and displays additional information about the Backup process.\\
![ASDM Backup Statistics window showing backup progress and details]()
12. Click OK\\
![ASDM backup completion confirmation dialog]()
## Restore Process
1. Establish a VPN connection to the MacStadium environment.
2. Connect to the firewall using the Cisco Adaptive Security Device Manager (ASDM).
3. Click Tools and select Restore Configuration from the dropdown menu.\\
![ASDM Tools menu with Restore Configuration option highlighted]()
4. Navigate to the location where the backup file was stored.\\
![Local file browser for selecting the backup ZIP file to restore]()
5. Click Select file.
6. Click Next to proceed.\\
![ASDM Restore Configuration Next button to proceed after file selection]()
7. From the Restore Configurations pop-up page, select the options to restore.
**Recommended settings:**
* Running configuration
* Start-up configuration
* All Security Images
* Identity Certificates
* Leave the remaining default options untouched
![ASDM Restore Configurations dialog with recommended restore options selected]()
8. Click Restore.
9. You should now see the below message. Click Yes.\\
![ASDM restore confirmation prompt asking to proceed with the restore]()
If applicable, enter the Certificate Passphrase used to backup the identity Certificate, then click OK.
![ASDM Certificate Passphrase prompt during restore process]()
The following message may appear during the Restore Progress. Select Refresh Now or Cancel button. Choosing Cancel will not halt the Restore process.
![ASDM restore progress message with Refresh Now option]()
10\. Once the Restore process is complete, click Close.
The Progress Message can be copied to a text editor for review and validation.
![ASDM restore progress log showing completion]()
11\. To verify the restore process, close the ASDM application and then relaunch it.
12\. Review the configuration that is loaded with the device manager.
13\. Close the application.
The following Unapplied Changes message box may appear:
![ASDM Unapplied Changes message box after restore]()
* If the Unapplied Changes message box appears, then click Apply Changes.
* If the Unapplied Changes message box does not appear, then click Save in the ASDM application.
## Additional Notes:
* If firewall access enables the backup process but does not enable the restore process, then open a MacStadium Support ticket.
* In the ticket, request that a restore take place for the firewall device.
* Provide the Firewall IP, the backup file, and permissions to perform the restore in the ticket.
* Request a specific time for the restore, or it will be performed as soon as possible.
# Changing the VPN & Firewall Password
Source: https://docs.macstadium.com/iaas/cisco-firewalls/changing-the-vpn-firewall-password
Change your initial Cisco ASA/ASAv firewall and VPN password using the Cisco ASDM-IDM interface. Credentials for the change are in your MacStadium IP Plan.
MacStadium provides the initial configuration of the firewall device, including a username and an initial password listed in the [IP Plan](/macstadium/macstadium-overview/ip-plan). Use these credentials to connect to the MacStadium cloud via VPN and to log in to the Cisco ASDM-IDM management interface of the firewall device.
For security reasons, change this password.
## Change the password
1. Verify login [logged in to your firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
2. Click Configuration.
![ASDM Configuration button in the main toolbar]()
3. Select Device Management.
4. Select Users/AAA > User Accounts.
5. Select the username to log in to Cisco ASDM-IDM and click Edit.
Do not edit the passwords for the enable and admin users. They are reserved for maintenance and support by the MacStadium team.
6. On the Identity screen, select the Change user password checkbox, set the new password, confirm it, and click OK.
7. At the bottom of the screen, click Apply.
## Next steps
* Update any scripts, documents or connection settings with the latest password.
* From the **Device Management > Users/AAA > User Accounts** interface, manage access to your cloud and the firewall by adding more users with specific [privilege levels](https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst3850/software/release/3se/security/configuration_guide/b_sec_3se_3850_cg/b_sec_3se_3850_cg_chapter_011.html#concept_F64909EAE01841CF83BDF991F2876CAE).
# Checking the Firewall Version
Source: https://docs.macstadium.com/iaas/cisco-firewalls/checking-the-firewall-version
Find your Cisco ASA/ASAv software version and device model in ASDM-IDM or the CLI. Needed before downloading VPN configs or filing a support ticket.
Sometimes, it is necessary to know the exact model of the Cisco ASA/ASAv device and its software version. For example, when downloading the VPN configuration file from Amazon, the following information is required: vendor, platform, and software version of the firewall device.
## Check model and version in Cisco ASDM-IDM
1. Verify login [logged in to your firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
2. In the menu bar of the running Cisco ASDM-IDM, select Help > About Cisco Adaptive Security Appliance (ASA).\\
![ASDM Help menu with About Cisco Adaptive Security Appliance option selected]()
3. In the pop-up window, look for the following information:
* Cisco Adaptive Security Appliance Software Version: Lists the software version of the firewall. For example: 9.8(2)24.
* Device Manager Version: Lists the software version of the Cisco ASDM-IDM interface. For example: 7.8(2).
* Model Id: Lists the device model. For example: ASAv5.
![ASDM About dialog showing software version, device manager version, and model ID]()
## Check model and version in the CLI
1. Verify login logged in to your firewall.
2. In the Cisco CLI, run the following command:\
`show version`
3. In the command response, look for the following information:
* Cisco Adaptive Security Appliance Software Version: Lists the software version of the firewall. For example: 9.8(2)24.
* Device Manager Version: Lists the software version of the Cisco ASDM-IDM interface. For example: 7.8(2).
* Model Id: Lists the device model. For example: ASAv5.
# Creating Local User Accounts on a Cisco ASA
Source: https://docs.macstadium.com/iaas/cisco-firewalls/creating-local-user-accounts-on-a-cisco-asa
Create local user accounts on a MacStadium Cisco ASA firewall using the CLI or ASDM. Used to manage VPN access via Cisco AnyConnect for specific users.
## Overview
Creating local user accounts on a Cisco Adaptive Security Appliance (ASA) is an essential task for Network Administrators, and is done to secure their network resources.
Local user accounts are useful for managing user access to the ASA and to the resources behind the ASA, through the use of a VPN client, such as Cisco AnyConnect.
This document describes how to create local user accounts on the Cisco ASA, using both the command-line interface (CLI) and the Adaptive Security Device Manager (ASDM). This document is intended for those who are managing the subscribed Cisco ASA appliance and want to learn how to create local user accounts.
The details in this document are based on a Cisco ASA virtual firewall that runs ASA code version 9.14(3)18 and ASDM version 7.18.(1)152, and was created from these devices in a specific lab environment.
The device used in this document started with a cleared (default) configuration.
For a live network, consider the potential impact before executing any commands.
MacStadium configured a shared user account for customers to use for accessing the firewall. It was also used for authentication for the environment behind the firewall, and used a Remote Access VPN (RAVPN) client. This user account was configured with the highest access level.
## Getting Started
To begin the steps on how to create additional local user accounts, obtain the existing account information from the [IP Plan](/macstadium/macstadium-overview/ip-plan).
## Install Options
Updating the Cisco Adaptive Security Appliance (ASA) can be done two different ways:
**Via Command Line Interface (CLI)**
Using a CLI allows you to write script changes in a notepad and have those changes reviewed by someone before running them. This method is good for writing scripts.
**Via Cisco Adaptive Security Device Manager (ASDM)**
Using an ASDM allows you to make line-by-line changes, while using a graphical user interface (GUI).
## Via Command Line Interface (CLI)
1. Establish a VPN connection to the MacStadium environment.
2. Connect to the Cisco ASA using SSH.
* *For more information, see the section Connect to the Cisco ASA using SSH.*
3. Use the credential documented in the IP Plan to authenticate; when prompted, enter a username and password.
4. Enter global configuration mode by typing the command `configure terminal`
5. Create the new user account by typing the command in the following format: `username username password password privilege priv_level`
* The `username` keyword is a string from 3 to 64 characters long. The space and question mark characters cannot be used for usernames.
* The `password` keyword is a string from 3 to 127 characters long. The space and question mark characters cannot be used within the passwords.
* The `privilege priv_level` keyword sets the privilege level for the created user account. The `priv_level` is a numeric value ranging from 0 to 15.
* By default, a user account has a privilege level of 2.
* A level of 15 grants the user account the highest level of access.
* Example: `ciscoasa(config)# username exampleuser1 password examplepassword privilege 1`
6. Save the configuration with the command `write memory`
7. Type the exit or end command to return to privileged mode of the ASA.
To confirm the creation of the user account, enter the command show `running-config username`
This command displays all the user accounts configured on the ASA.
```
ciscoasa# show running-config username
username exampleuser1 password ***** pbkdf2 privilege 1
username clientuser1 password ***** pbkdf2 privilege 15
username admin password ***** pbkdf2 privilege 15
ciscoasa#
```
When a password is defined in the username command, the ASA creates an MD5 hash of it when it is saved for security purposes. When verifying configuration with the show running-config command, the username command does not show the actual password; it shows the encrypted password followed by the encrypted keyword.
### Testing a Newly Created Account
1. In privilege mode, enter the command `disable`
2. Enter the command `login`
3. At the Username prompt, enter the created username.
4. At the Password prompt, enter the created password.
If the authentication is successful, then proceed to test the level of access for the user account either at the ASA or at the RAVPN client.
```
ciscoasa # disable
ciscoasa > login
Username: exampleuser1
Password: ***************
ciscoasa > enable
Password: *********
Password: ***************
```
**Unsuccessful Authentication**
```
[ exampleuser1 ] You do NOT have Admin Rights to the console !
```
**Password**
To remove a user account, use `no version` with the username that is being removed.
**Removing a User Account**
1. Log into the firewall with an account different from the account being removed.
2. Enter global configuration mode by typing the command `configure terminal`
3. Enter the `no version` of the username command.
4. Enter the `exit` or `end command` to return to privilege mode.
5. Save the configuration with the command `write memory`
6. Verify the changes made with the command `show running-config username`.
```
ciscoasa# configure terminal
ciscoasa(config)# no username exampleuser1
ciscoasa(config)# end
ciscoasa# write memory
Building configuration...
Cryptochecksum: b327981a 7a0e4ca2 ba149024 d05c9ab5
24790 bytes copied in 0.60 secs [OK]
ciscoasa# show running-config username
username admin password ***** pbkdf2 privilege 15
username clientuser1 password ***** pbkdf2 privilege 15
```
## Via Cisco Adaptive Security Device Manager (ASDM)
**Creating a Local User Account with ASDM**
1. Open the ASDM and connect to the Cisco Adaptive Security Appliance (ASA).
2. Click Configuration.\\
![ASDM Configuration button in the main toolbar]()
3. Click Device Management.\\
![ASDM Device Management section in the configuration panel]()
4. Click Users/AAA.\\
![ASDM Users/AAA menu under Device Management]()
5. Click Add to create a new user account.
6. In the Add User Account window, confirm that Identity is selected at the left of the window and then enter the username and password for the new user account.
* Specify a Access Restriction by selecting an option in the section below.\\
![Add User Account dialog with username, password, and access restriction fields]()
7. Click OK to save the new user account
8. Click Apply located at the bottom of the ASDM
9. Click Save
Test the new account by logging out of the ASDM and then logging back in with the new credentials.
#### **Removing an Account from the Local Database**
1. Under the User Accounts of the ASDM, select the user account to be removed.
2. Click Delete
3. Click Apply
4. Click Save
For information on Advanced Options for user account creations and management, see the following guides:
[Cisco ASDM 7.18 AAA Local User Guide](https://www.cisco.com/c/en/us/td/docs/security/asa/asa918/asdm718/general/asdm-718-general-config/aaa-local.html)
[Cisco ASA 9.14 AAA Local User Guide](https://www.cisco.com/c/en/us/td/docs/security/asa/asa914/configuration/general/asa-914-general-config/aaa-local.html)
## Connect to the Cisco ASA using SSH
1. Configure aaa to use local database for ssh and console:
```
ciscoasa# aaa authentication ssh console LOCAL
```
`aaa` = authentication (permitting access), authorization (specify commands when granted access), accounting (keeps track of utilization reports of users after logged in and generates accounting reports for billing). `LOCAL` = local database.
2. Create admin username with privilege 15:
```
ciscoasa# username username password P@ssw0rd priv 15
```
`priv 15` = top privilege level (full superuser, can give different command access to different privilege levels).
3. Turn on password for enable:
```
ciscoasa# aaa authentication enable console LOCAL
```
This forces a password for the enable prompt.
4. Turn on serial console authentication:
```
ciscoasa# aaa authentication serial console LOCAL
```
This turns on user/pass for serial access.
5. Save changes:
```
ciscoasa# write mem
```
6. Log out console and verify access.
`ciscoasa(config)# end`
`ciscoasa# exit`
`Username: username`
`Logoff`
`Password: ********`
7. Generate ssh key pair:
```
ciscoasa# crypto key generate rsa modulus 4096
```
SSH is an encrypted protocol that uses RSA to generate public and private keys. `4096` = block size, `rsa` = encryption algorithm. The prompt will show `Keypair generation process begin. Please wait…` followed by `ciscoasa(config)#`.
8. Allow access to the inside interface:
```
ciscoasa# ssh 0.0.0.0 0.0.0.0 inside
```
This enables SSH access to the inside interface from any IPv4 address.
9. Force ssh version 2:
```
ciscoasa# ssh version 2
```
10. Add a 15-minute timeout to ssh:
```
ciscoasa# ssh timeout 15
```
11. Verify login with ssh through 192.168.1.1 in putty.
# Firewall Change Request Form
Source: https://docs.macstadium.com/iaas/cisco-firewalls/firewall-change-request-form
Download the MacStadium Firewall Change Request Form (Word doc) and submit to the support team to request Cisco ASA/ASAv firewall configuration changes.
## About
[Download the Firewall Change Request Form here](https://prismic-io.s3.amazonaws.com/macstadium/80237b25-a824-478a-9ef0-fd2211aa79bf_MacStadium+Firewall+Change+Request+Form.docx) (Microsoft Word document) and share it with the MacStadium Support team by opening a ticket or emailing [support@macstadium.com](mailto:support@macstadium.com).
# Logging into Cisco Firewall
Source: https://docs.macstadium.com/iaas/cisco-firewalls/logging-into-cisco-firewall
Log into your MacStadium Cisco ASAv via ASDM-IDM. Prerequisites: Java installed, active VPN, and credentials from the MISC sheet in your IP Plan.
## Download and install Cisco ASDM-IDM
The dedicated Cisco firewall comes with a management interface: **Cisco ASDM-IDM**.
1. Make sure the VPN is connected. For more information about how to connect to the VPN, see [Connecting to Your Cloud (via VPN)](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Confirm that Java is installed on the system.
Download and install an official Java distribution from [Oracle](https://www.oracle.com/technetwork/java/javase/downloads/index.html). Java installations from package managers or OpenJDK installations might not work.
3. In the browser, navigate to the Cisco ASDM-IDM download location provided in the MISC sheet of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
4. Ignore the certificate warning and proceed to the address.
5. Click Install ASDM Launcher.
6. When prompted for credentials, provide the VPN credentials with Cisco AnyConnect. They are in the Step 1: VPN section of the One Page sheet of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* For more information about how to change the VPN & firewall password, see [Changing the VPN & Firewall Password](/iaas/cisco-firewalls/changing-the-vpn-firewall-password).
7. Launch the downloaded installer.
8. (macOS-only) If prompted that the installer cannot be opened because it is from an unidentified developer, then complete the following steps.
* Navigate to **System Settings > Privacy & Security > General**.
* Locate the `"Cisco ASDM-IDM" was blocked from opening because it is not from an identified developer.` note and click Open Anyway.
* In the pop-up window, click Open and confirm the required permissions.
After the installation completes, the Cisco ASDM-IDM Launcher loads.
## Log into the firewall
Use the Cisco ASDM-IDM Launcher to reach and configure the firewall.
1. Run the Cisco ASDM-IDM Launcher, if not already running.
2. Enter the following data and click OK:
* For Device IP Address / Name, provide the IP address from the MISC sheet of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* For Username and Password, provide the VPN credentials used with Cisco AnyConnect. They are in the Step 1: VPN section on the One Page sheet of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* **TIP**: If nothing happens or a connection error occurs, then confirm the VPN connection and try again.
3. If prompted that the connection is untrusted, click Continue. The first time connecting to it might take longer, due to software updates.
* **TIP**: Keep the VPN password handy. Cisco ASDM-IDM might prompt for it at different times.
# Managing Cisco ASA firewall interfaces via ASDM
Source: https://docs.macstadium.com/iaas/cisco-firewalls/managing-interfaces
View and configure Cisco ASA firewall interfaces using the ASDM graphical management tool. Access settings via Configuration, Device Setup, and Interfaces.
Manage interfaces via the Cisco Adaptive Security Device Manager (ASDM), which is done via **Configuration > Device Setup > Interfaces**.
The Cisco ASDM delivers world-class security management and monitoring through an intuitive, easy to use management interface. As ASDM is a client, it can run on workstations, desktops, and laptops.
The Misc tab on the IP Plan contains specific instructions and links for downloading the Cisco ASDM client.
## Plan Misc Tab
Once behind the firewall via VPN, access the environment either via ASDM or by Secure Shell (SSH).
## ASDM Data Sheet
The ASDM data sheet can be [found here](https://www.cisco.com/c/en/us/products/security/asa-5500-series-next-generation-firewalls/data_sheet_c78-345385.html).
## DMZs
A DMZ is a server reachable by outside IP addresses, but which can also communicate with inside IP addresses, too. It provides a method of communication between inside and outside IP addresses. Customers ultimately define their own DMZs. This can also be configured via ASDM.
* [Cisco ASA DMZ Configuration Example](https://www.speaknetworks.com/cisco-asa-dmz-configuration-example/)
* [Configure a Public Server with Cisco ASDM](https://www.cisco.com/c/en/us/support/docs/security/asa-5500-x-series-next-generation-firewalls/113425-asdm-pub-server-00.html)
* [How to Set up a Cisco ASA DMZ](https://www.youtube.com/watch?v=eeTZZN5U858) (video)
## Logging
Firewalls can log how they handle various types of traffic. For forensic purposes, information like source and destination IP addresses, port numbers, and protocols can be invaluable. However, the downside of logging is that the size of log files can quickly become unwieldy. Because of this, MacStadium has logging turned off by default. However, it is easy to change and configure this setting to capture traffic details.
To turn *logging* on, you first need to identify a repository for the log information. MacStadium recommends designating a separate repository for those log files, because it can grow quickly. You can set this in ASDM via **Monitoring > Logging**. You can also submit a firewall change request via the MacStadium Portal to select a new repository.
If you run CI as a service, port those logs to a separate server. Otherwise, speed, storage, and performance may be impacted. MacStadium also recommends leaving logging disabled, especially for internal-only configurations.
For more information, see [Cisco Logging Best Practices](https://tools.cisco.com/security/center/resources/firewall_best_practices#43).
### Command Line Interface
For expert users, the Command Line Interface (CLI) can provide an elegant and convenient option for configuring your firewall.
To access the CLI, first connect via your VPN. Then SSH to the IP address of the inside interface found in your connection information available via the MacStadium portal.
## Command Line Interface (CLI)
[Cisco ASA 5500 Series Command Reference, 8.2](https://www.cisco.com/c/en/us/td/docs/security/asa/asa84/configuration/guide/asa_84_cli_config.html)
## Connecting to Another Public Cloud
### Site to Site VPN
Site to Site VPNs are designed to connect a firewall to a firewall, a router to a router, or a router to a firewall. With a Site to Site VPN properly configured, MacStadium customers can connect their environments to an AWS implementation or another public cloud.
MacStadium supported Site to Site VPN is a standard IPsec site-to-site implementation. Most customers can set that up in ASDM very similarly to how they create other VPN connections, via the VPN Wizard.
Wizards > Site-to-Site VPN Connection Setup Wizard
The VPN Wizard by default creates the most generic and compatible tunnel you can make. MacStadium supports two versions, traditional Internet Key Exchange (IKE) methods IKEv1 vs IKEv2. More information on configuring each can be found below:
* [Configuring Internet Key Exchange Version 2 (IKEv2)](https://www.cisco.com/en/US/docs/ios-xml/ios/sec_conn_ike2vpn/configuration/15-2mt/sec-cfg-ikev2-flex.html)
* [Configure IKEv1 IPsec Site-to-Site Tunnels with the ASDM or CLI on the ASA](https://www.cisco.com/c/en/us/support/docs/security/asa-5500-x-series-next-generation-firewalls/119141-configure-asa-00.html)
* [Configure a Site-to-Site IPSec IKEv1 Tunnel Between an ASA and a Cisco IOS Router](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/119425-configure-ipsec-00.html)
* [Cisco ASA Site-to-Site IKEv1 IPSec VPN](https://networklessons.com/cisco/asa-firewall/cisco-asa-site-site-ikev1-ipsec-vpn)
## IPSec VPN
If your optimum environment requires an IPSec VPN connection, MacStadium supports this method of connection. Be aware that IPSec VPN is no longer supported by Windows post Windows 8. However, Macs still support this method of connection out of the box.
For specific instructions on configuring an IPSec VPN from macOS, see [How to Setup an IPSec VPN Connection from macOS](https://support.apple.com/en-gb/guide/mac-help/mchlp2963/mac).
## Virtual Tunneling Interface (VTI)
MacStadium also supports IPSec VTI. Tunnel interfaces have many uses, including participating in a larger VPN configuration. MacStadium supports a Border Gateway Protocol (BGP) based tunnel. This is the best method for connecting to an AWS implementation.
Be advised VTI is not supported on older model ASA appliances (5585, 5540, etc).
## IPSec Virtual Tunnel Interface
If you want to have lots of VMS that live on a few IP addresses, you may want to utilize port forwarding instead of the internal public addresses. Port forwarding is a method of making your MacStadium private cloud accessible to specific IP addresses on the internet, even though you are behind a firewall.
Port forwarding to VMs must be statically defined on the firewall.
[Configure ASA Version 9.x Port Forwarding with NAT](https://www.cisco.com/c/en/us/support/docs/ip/network-address-translation-nat/118996-config-asa-00.html)
## Rules
You can create custom rules for your firewall as if it was in your own environment. Rules can be configured in ASDM via **Configuration > Firewall > Access Rules**.
## Best Practices
* Keep in mind that rules are processed in order.
* Only create rules on the outside interface, and leave others saying “any.”
* Unless you are an expert, we recommend that you don’t filter any outbound traffic. If you do choose to filter outbound traffic, be very specific with ALL traffic heading outbound so you don’t inadvertently block legitimate traffic. Start by using a rule that permits everything and then narrow down.
* You will need both a Network Address Translation (NAT) rule and an access rule working in conjunction, as either alone won’t work. A typical use case would be creating an SSH rule tied to a Jenkins master (if you don’t use a VPN).
* If you don’t have experience with ASAs, just do a 1:1, where one internal IP address behind the interface is mapped to one external IP address.
## Dynamic Host Configuration Protocol (DHCP)
If DHCP is integral to your solution, you can use a VM on your network to control it. Keeping DHCP on a separate VM keeps your environment safe in case you need to restart your DHCP server.
## Configuring the Cisco IOS DHCP Server
### DHCP Relay
DHCP Relay permits DHCP clients and servers to be placed on numerous networks. The DHCP relay agent will respond to a broadcasted “discover” request and reply to the relay server. It sends the offer back to the DHCP device and sends it back to the original requester.
### Configuring the Cisco IOS DHCP Relay Agent
Documentation can be found [here](https://www.cisco.com/en/US/docs/ios/12_4t/ip_addr/configuration/guide/htdhcpre.html).
## Best Practices for Continuous Integration
CI/CD projects are by their nature unique, and hence will also benefit from a custom firewall configuration that corresponds to your individual needs.
MacStadium recommends putting your build farm elements in private space. This allows environments to grow and shrink on demand. Another reason to place these elements in private space is that a lot of CI/CD traffic is necessarily east/west. If they all live in the same VLAN, then communications between VMs can be direct and not have to go through the firewall.
## Support
If you require additional help with your firewall, please contact MacStadium support.
# Network Firewalls Cloud Connect VPN
Source: https://docs.macstadium.com/iaas/cisco-firewalls/network-firewalls-cloud-connect-vpn
Connect to your MacStadium Orka cluster via Cisco ASAv VPN with OpenConnect or Cisco AnyConnect. Requires server address and credentials from your IP Plan.
**Requirements:**
* The server address from **Step 1: VPN** in the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* The username and password from **Step 1: VPN** in the [IP Plan](/macstadium/macstadium-overview/ip-plan).
## About
To protect the environment, MacStadium deploys the Orka cluster with a dedicated [Cisco Adaptive Security Virtual Appliance](https://www.cisco.com/c/en/us/products/collateral/security/adaptive-security-virtual-appliance-asav/datasheet-c78-733399.html) (ASAv) firewall. Cisco ASAv runs the same software as physical Cisco ASAs and delivers full ASA firewall and VPN capabilities to the cloud.
The Orka cluster sits behind its dedicated Cisco ASAv firewall, which must be connected to the cluster via VPN to do any of the following tasks:
* Manage the Orka VMs and K8s pods.
* Log in to the firewall and manage connectivity between the cluster and the outside world (for example, enterprise networks, other private and public clouds).
MacStadium has pre-configured the firewall and has enabled VPN access. Simply run a VPN client and provide the server address and credentials for the connection.
## Overview
**(Open-source option) OpenConnect**
For users who are comfortable working with a Command Line Interface (CLI) or in a Terminal, consider using OpenConnect - an open-source VPN client available from the command line.
**Download and Install OpenConnect**
* If [Homebrew](https://brew.sh/) is enabled on the system, then run `brew install openconnect` from the command line.
* Windows users, can [download](https://www.infradead.org/openconnect/download.html) and [build](https://www.infradead.org/openconnect/building.html) the OpenConnect package or use [Cisco AnyConnect](/iaas/cisco-firewalls/network-firewalls-cloud-connect-vpn) instead.
**Configure OpenConnect to Access Orka via Custom Domain**
To be able to reach the custom Orka domain API endpoint, add a DNS server to the network configuration.
The DNS server address is the `.251` address for the `Private-1` network from the [IP Plan](/macstadium/macstadium-overview/ip-plan). For example: `10.10.10.251` or `10.221.188.251`.
**macOS**
1. Go to **System Settings > Network**.
2. From the list of network connections, select the current Internet connection, locate and click the Advanced... button at the right bottom corner of the dialog.
3. Go to the DNS tab.
4. At the bottom of the DNS Servers list, click **+**.
5. Type the Orka DNS address and press Enter.
6. If not already at the top, drag and drop the Orka DNS server to the top. It must be the first item in the list.
7. Click **OK.**
8. Click **Apply.**
9. Exit **System Settings**.
**Linux**
1. Use a text editor to open `/etc/resolv.conf`.
2. Locate the nameserver section and add the Orka DNS address:
```
nameserver
```
3. Make sure that this is the first nameserver entry in the list.
**Windows**
1. Go to **Control Panel > Network and Internet**.
2. Under Network and Sharing Center, select View network and status.
3. In the Network and Sharing Center, in the sidebar, select Change adapter settings.
4. In the Network Connections window, right-click the current Internet connection and select Properties.
5. Go to the Networking tab, scroll down and click Internet Protocol Version 4 (TCP/IPv4).
6. With Internet Protocol Version 4 (TCP/IPv4) highlighted, click Properties.
7. Go to the General tab and select Use the following DNS server addresses.
8. Add the Orka DNS server as the Preferred DNS server. Add any other name server as the Alternate DNS server (for example, 8.8.8.8).
9. Click **OK**.
10. Click **Close**.
### Use OpenConnect
1. From the command line, run the following command. Replace `` with the server address from Step 1: VPN in the IP Plan.
```
sudo openconnect --protocol=anyconnect
// OR if running on Windows
openconnect --protocol=anyconnect
```
2. Follow the prompts.
* On the immediate Password prompt, provide the sudo password (the password for the current computer user) and press Enter.
* On the Enter 'yes' to accept, 'no' to abort; anything else to view: prompt, type yes and press Enter.
* On the Username prompt, provide the username from Step 1: VPN in the IP Plan and press Enter.
* On the Password prompt, provide the password from Step 1: VPN in the IP Plan and press Enter.
When the connection is established, a similar output (show below) appears:
![openconnect-1.png]()
**Want to terminate the VPN connection?**
At any time press `Ctrl+C` on the command line.
## Cisco AnyConnect Secure Mobility Client
Cisco firewalls are designed to work with the [Cisco AnyConnect Secure Mobility Client](https://www.cisco.com/c/en/us/support/security/anyconnect-secure-mobility-client/tsd-products-support-series-home.html) as a VPN client. For a GUI VPN client or that is running on Windows, use Cisco AnyConnect.
### Download and install Cisco AnyConnect
1. In the browser, navigate to the server address from Step 1: VPN of the [IP Plan](/macstadium/macstadium-overview/ip-plan). Use https\://.
2. Ignore the certificate warning and proceed to the address.
3. When prompted, enter the credentials from Step 1: VPN in the IP Plan.\\
![openconnect-2.png]()
4. When prompted, download, install, and run the Cisco AnyConnect desktop client.\\
![openconnect-3.png]()
### Configure AnyConnect to access Orka via custom domain
On Windows, to be able to reach the custom Orka domain with AnyConnect, add a DNS server to the network configuration.
On macOS and Linux, no changes are required.
The DNS server address is the `.251` address for the `Private-1` network from the [IP Plan](/macstadium/macstadium-overview/ip-plan). For example: `10.10.10.251` or `10.221.188.251`.
**Windows**
With Cisco AnyConnect already connected to your cluster:
1. Go to **Control Panel > Network and Internet**.
2. Under Network and Sharing Center, select View network and status.
3. In the Network and Sharing Center, in the sidebar, select Change adapter settings.
4. In the Network Connections window, right-click Cisco AnyConnect Secure Mobility Client Connection and select Properties.
5. Go to the Networking tab, scroll down and click Internet Protocol Version 4 (TCP/IPv4).
6. With Internet Protocol Version 4 (TCP/IPv4) highlighted, click Properties.
7. Go to the General tab and select Use the following DNS server addresses.
8. Add the Orka DNS server as the Preferred DNS server. You can add any other name server as the Alternate DNS server (for example, 8.8.8.8).
9. Click **OK**.
10. Click **Close**.
### Use Cisco AnyConnect
1. Run Cisco AnyConnect Secure Mobility Client.
2. When prompted, enter the server address from Step 1: VPN of your IP Plan and click Connect.
![ciscologin.png]()
3. If prompted that an untrusted server was blocked, perform the following steps:
* Click Change Setting... and deselect Block connections to untrusted servers.
* Close the Preferences - VPN window.
* Click Connect again.
![blockconnections.png]()
4. If prompted that the server certificate is untrusted, click Connect Anyway.
5. When prompted, provide login credentials and click **OK**.
# Network Firewalls Configuration
Source: https://docs.macstadium.com/iaas/cisco-firewalls/network-firewalls-configuration
Overview of the MacStadium Cisco ASAv firewall: admin root access, available configuration options, and how to request changes via the Customer Portal.
Every MacStadium private cloud deploys with a dedicated Cisco firewall to protect and secure the entire infrastructure. MacStadium dedicated firewalls provide admins with root access to the firewall and the ability to configure settings to their specifications. This guide describes some of the most popular configuration and customization options available to MacStadium customers.
## Getting Started
Many customers simply submit a ticket via the [MacStadium portal](https://portal.macstadium.com/) with their firewall configuration requests.
### Cisco Adaptive Security Virtual Appliance (ASAv)
MacStadium offers Cisco Adaptive Security Virtual Appliance (ASAv), which runs the same software as physical Cisco ASAs. This means that we are able to deliver full ASA firewall and VPN capabilities to cloud environments that help safeguard traffic and multitenant architectures. Optimized for data center deployments, the ASAv is designed to work as a virtual machine. The advantage for MacStadium customers of using a virtual firewall comes from faster deployments and easier upgrades. We recommend ASAv firewalls for all use cases that have sustained throughput demands of less than 500 Mbps (125 Mbps Encrypted) as it delivers exceptional security and performance at a great price.
With a Cisco ASAv protecting their MacStadium private cloud, customers can:
* Implement uniform security across multiple physical and virtual domains
* Accelerate provisioning with predetermined configurations
* Simplify management by using representational state transfer (REST) APIs to manage the device, easily introduce Cisco ASAv into software-defined networking (SDN) environments, and incorporate ASAv into custom policy-orchestration systems.
The virtual appliance supports the same site-to-site VPN, remote-access VPN, and client-less VPN functionalities that physical ASA devices do. Most of the features that are supported on a physical ASA by Cisco software are also supported on the virtual appliance, with the notable exceptions of Cisco not supporting clustering and multiple contexts support (that is to say, having multiple separate *virtual* firewalls on the same hardware) on ASAv implementations.
### Cisco Adaptive Security Appliance (ASA)
MacStadium also offers physical ASA hardware devices for customers who require those capabilities or need more throughput than a virtual firewall can handle. The standard appliance MacStadium offers is a Cisco ASA 5500 series firewall, and is for any customer who needs a dedicated, physical security appliance to protect their host environment.
When customers need even more power for inspection and protection, MacStadium also offers Cisco Firepower 2100 NGFW series appliances. The main difference between the two appliances is in an increase of 10 gigs per second in speed, connections and packets per second for the 2100 series.
Both the Cisco 5500 and 2100 series deliver:
Market-proven security capabilities that integrate multiple full-featured, high-performance security services, including application-aware firewall, SSL and IPsec VPN, IPS, antivirus, anti-spam, anti-phishing, and web filtering services.
Comprehensive management interfaces including the graphical Cisco Adaptive Security Device Manager (ASDM), a comprehensive command line interface (CLI), verbose syslog, and Simple Network Management Protocol (SNMP) support that round out a rich complement of management options.
For more information, please contact MacStadium Support or Sales.
Hardware firewalls are not typically available during free trials or POC periods.
## Other Options
There are several firewall options for users who do not want to use Cisco ASA technology.
### Software Firewalls
By default, MacStadium gives the maximum flexibility by leaving all ports open to the internet. Because of this, it is highly recommended to implement another form of defense when not using the MacStadium dedicated Cisco firewall. There is a comprehensive list of third party software firewalls, including feature and price comparisons, at Mac Security: Firewalls.
Please be advised that MacStadium does not offer support for third party software firewall solutions. Also, please take the time to understand the potential impacts of enabling a third-party firewall. If errors exist in the configuration, then there is an increased risk of a data breach. As always, keep the credentials in a safe place.
### macOS X Firewall
Apple also includes a serviceable firewall with OSX. Information on its capabilities and how to enable it can be found at OS X: About the application firewall.
#### Customized and Hybrid Deployments
We understand that many customers have unique security requirements and may wish to host their own firewalls in our data centers. Our engineering team has detailed experience with many other security appliances and can assist your team in implementing your best possible network security configuration.
You can access firewall add-ons from the MacStadium Portal under the **Add-Ons** tab in your subscription details.
Please contact Sales for more information.
### Configuring Access
After submitting a private cloud request, the MacStadium provisioning team creates a ticket accessible via the MacStadium portal that contains the connection information.
The IP plan contains necessary information including how to gain access to the private cloud, instructions for accessing vCenter client (unless it is a bare metal implementation), IP allocation, and host assignments.
Setting up Access with a Remote Access Virtual Private Network (VPN)
For security reasons, outside access to the firewall is blocked by default. The recommended method, and the one most MacStadium customers follow, is to access private cloud via a Remote Access Virtual Private Network (VPN).
![MacStadium IP Plan showing VPN connection information and credentials]()
VPN is the easiest way to securely connect to MacStadium private cloud. The recommended method of doing this is via the AnyConnect client. Instructions for configuring and connecting are here:
Configure Cisco AnyConnect Secure Mobility Client
If the connection information mentions Group Authentication, then configure an IPSec VPN connection. Instructions for doing so on macOS and Windows installations follow:
![MacStadium IP Plan showing IPSec VPN group authentication configuration]()
This tutorial (images only) displays how to deploy a virtual machine using the VMware web client. For more information concerning VMware and the VMware vCenter Server Virtual Appliance (vCSA), see the VMware Quick Start Guide.
### IP Allocation and Host Assignments
![a4721e1-5be45d861ec311056ee262a5_ipallocation.png]()
MacStadium defines four basic interface types for customer use:
1. Outside: External firewall management addresses
2. Inside: /28 range
3. ESXi-MGMT: Reserved for vCenter & ESXi hosts (should not have public IP addresses)
4. Private: Random private range assigned for your use – by default no outside access allowed
What interfaces appear in the initial connection information on the MacStadium portal depends on your private cloud configuration request. For instance, for a bare metal implementation, there is no information concerning ESXi management and vCenter.
# Network Firewalls for CI Build Node: Ansible
Source: https://docs.macstadium.com/iaas/cisco-firewalls/network-firewalls-for-ci-build-node-ansible
Set up a macOS CI build node with the MacStadium Ansible playbook. Installs Homebrew, Xcode, fastlane, CocoaPods, and optionally Java for Jenkins.
This guide details how to install the build tools needed to set up a CI Build Node using Ansible.
Minimum requirements:
* [Homebrew](https://brew.sh/)
* [fastlane](https://fastlane.tools/)
* [CocoaPods](https://cocoapods.org/)
* [Xcode](https://developer.apple.com/xcode/)
* [Java 8](https://www.oracle.com/technetwork/java/javase/overview/java8-2100321.html) is also a requirement to set up a Jenkins agent
Finally, it is a good practice to have a bot user whose only responsibility is to build your OSX/iOS projects. This means such a user with the correct permissions should be created, so the user can build OSX/iOS projects.
The recommended way to set up a CI Build Node is to use [Ansible](https://www.ansible.com/).
Ansible is a configuration management tool that is used to automate the setup of a specific system. It can define the system as code. This makes changes to a specific system easier and most importantly, track who changed what and how. Users unfamiliar with Ansible, should read [quickstart video](https://www.ansible.com/resources/videos/quick-start-video). It gives a good idea of what Ansible is and how it can be used.
MacStadium provides an [Ansible playbook](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html) that takes care of the installation and setup of the tools need for a CI Build Node. The playbook is open-source and can be found [here](https://github.com/macstadium/ansible-playbook-osx-ci-setup).
The playbook works for OSX High Sierra and Mojave. It is capable of installing Xcode 8 and above. If you are using an older OSX version or require an older Xcode version, refer to our manual installation guide.
The playbook is intended to be executed on the machine to set up as a CI Build Node. To execute the playbook remotely, to configure another [Ansible inventory](https://docs.ansible.com/ansible/2.4/intro_inventory.html).
The Xcode installation requires a UI session. This means the user that executes Ansible must be logged in. For example, if Ansible with admin is executed, then the user must make sure that this user is logged in. This is achieved via VNC or via the Web Console.
## Ansible Playbook
### Initial setup
The first step is to connect to the target machine. Do this via VNC or via the Web Console, or enable Remote Login in the macOS settings, then SSH in.
To download and run the setup script contained in the [repository](https://github.com/macstadium/ansible-playbook-osx-ci-setup). To do that run the following commands:
```
curl https://raw.githubusercontent.com/macstadium/ansible-playbook-osx-ci-setup/master/scripts/ansible_setup.sh -o ~/ansible_setup.sh
chmod +x ~/ansible_setup.sh
sudo ~/ansible_setup.sh
```
This installs:
* Xcode Command Line Tools
* [pip](https://pip.pypa.io/en/stable/)
* [Ansible](https://www.ansible.com/)
Now clone the [repository](https://github.com/macstadium/ansible-playbook-osx-ci-setup) containing the Ansible playbook.
This is done by running:
```
git clone https://github.com/macstadium/ansible-playbook-osx-ci-setup.git
```
This playbook consists of two roles:
* [OSX-CI](https://github.com/macstadium/ansible-role-osx-ci) - Installs all common tooling and creates a user capable of running build jobs
* [Xcode](https://github.com/macstadium/ansible-role-xcode) - Installs and configures Xcode
To install these two roles execute:
```
cd ansible-playbook-osx-ci-setup
ansible-galaxy install -r requirements.yml
```
## OSX-CI Role Requirements
The [OSX-CI](https://github.com/macstadium/ansible-role-osx-ci) requires a path to a public ssh key on the target machine. The role adds the key to the `authorized_keys` file of the created user to enable remote login via ssh with a private key.
To use the target machine as a Jenkins agent you will need a key pair generated using the `RSA` algorithm.
If you do not have a ssh key pair you can create one by executing on the target machine:
```
ssh-keygen -m PEM -t rsa -C "build machine key" -f "buildMachine_rsa"
```
For increased security, it is recommended to associate a passphrase to the private key.
The command creates two files:
* buildMachine\_rsa - This is the private key. Keep it safe and **do not** share it with anyone.
* buildMachine\_rsa.pub - This is the public key.
To copy the private key to a secure machine, use `scp`. This command executes copy over SSH; run:
```
scp /path-to-buildMachine_rsa/ username@host:/path-to-location-on-secure-machine
```
## Xcode Role Requirements
The [Xcode](https://github.com/macstadium/ansible-role-xcode) needs a Xcode xip file to be present on the target machine. Get the version needed from the [Apple Downloads Page](https://developer.apple.com/download/more/).
## Password Encryption
The playbook requires a privilege escalation password:
```
ansible_become_pass
```
To specify a password which will be used to create a default keychain for the build user:
```
ci_user_default_keychain_password:
```
It is highly recommended not to pass the passwords in plain text.
To encrypt use [Ansible Vault](https://docs.ansible.com/ansible/latest/user_guide/playbooks_vault.html).
Add the variable to `group_vars/all.yml` and execute the following command:
```
ansible-vault encrypt group_vars/all.yml
```
A vault password is required and is later used to decrypt the file. Once the operation is executed the file is encrypted.
## Running the Ansible Playbook
To execute the Ansible playbook you can use the following command by replacing the `{placeholders}` with the correct values:
```
ansible-playbook site.yml -i inventory -e ansible_user={AdminUser} -e xcode_xip_location={XcodeLocation} -e xcode_major_version={XcodeMajorVersion} -e ci_user_public_key_location={PublicSshKeyLocation} --ask-vault-pass
```
You will be prompted for the vault password that you used to encrypt the `group_vars/all.yml` file in the previous step.
Once the execution is completed, you will have a fully-setup machine that you can use for OSX/iOS builds and for a Jenkins agent.
# Network Firewalls for CI Build Node: Homebrew
Source: https://docs.macstadium.com/iaas/cisco-firewalls/network-firewalls-for-ci-build-node-homebrew
Set up a macOS CI build node on MacStadium with Homebrew: install Ruby, fastlane, CocoaPods, and Xcode, with bot user best practices for iOS builds.
This guide details how to install the build tools needed to set up a CI Build Node using Homebrew.
Minimum requirements:
* [Homebrew](https://brew.sh/)
* [fastlane](https://fastlane.tools/)
* [CocoaPods](https://cocoapods.org/)
* [Xcode](https://developer.apple.com/xcode/)
* [Java 8](https://www.oracle.com/technetwork/java/javase/overview/java8-2100321.html) is also a requirement to set up a Jenkins agent
It is a good practice to have a bot user whose only responsibility is to build your OSX/iOS projects. This means such a user with the correct permissions should be created, so the user can build OSX/iOS projects.
Do this via VNC or via the Web Console, or to enable Remote Login in the macOS settings, set SSH in.
## Install Homebrew
[Homebrew](https://brew.sh/) is a package manager for macOS and used for managing installation of the various tools needed for iOS and macOS CI efforts. This step takes about 15 minutes, and requires the password at least once.
## Install Ruby
Lots of tooling requires a modern Ruby installed (fastlane for instance), so we also update our system Ruby:
```
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install rbenv ruby-build
# Add rbenv to bash so that it loads every time you open a terminal
echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile
source ~/.bash_profile
# Install Ruby
rbenv install 2.4.2
rbenv global 2.4.2
ruby -v
```
## Install fastlane
[fastlane](https://fastlane.tools/) provides an easy way to automate beta deployments and releases for iOS and Android apps.
To install it, run:
```
sudo gem install fastlane -NV
```
## Install CocoaPods
[CocoaPods](https://cocoapods.org/) is a dependency manager for Swift and Objective-C Cocoa projects. It is installed via ruby gem:
```
sudo gem install cocoapods
```
## Install Node.js
To install the latest version of Node.js run:
```
brew install node
```
To install the latest LTS run:
```
brew install node@10
brew link node@10 --force
```
This installs Node.js 10 LTS and links it to `/usr/local/bin` so it is available in `PATH`.
Consider using [nvm](https://github.com/creationix/nvm) to manage different Node.js versions. To install nvm run:
```
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
```
## Install Java 8
To setup a Jenkins agent, Java 8 must be installed on the machine.
To do that, run:
```
brew tap homebrew/cask-versions
brew cask install java8
```
## Install Xcode
Do this is via a VNC/screen-sharing session. If working from a Mac, open the Finder and press "cntrl k". This opens the machine's built-in VNC GUI. Collect your public IP and screen-sharing port, and pass them in the GUI.
1. Enter the user credentials.
2. Open a web browser via the screen-sharing connection.
3. Navigate to [developer.apple.com](https://developer.apple.com)
4. Log in
5. Navigate to [developer.apple.com/downloads/more](https://developer.apple.com/downloads/more)
6. Download and install the preferred version of Xcode by clicking the download link and double-clicking on the resulting download.
## Creating Dedicated Build User
MacStadium recommends having a dedicated user that is responsible for building OSX/iOS applications.
First, create a group for this user. The group needs to have a unique ID. List the current group IDs in a numerical order by running:
```
dscl . -list /Groups PrimaryGroupID | awk '{print $2}' | sort -n
```
Choose a number that is not in the list. Then run by replacing \{GroupName} and \{GroupID} with the desired values:
```
sudo dscl . -create /Groups/{GroupName}
sudo dscl . -create /Groups/{GroupName} PrimaryGroupID {GroupID}
```
Pick a unique ID for the user. It is done in a similar fashion to the way we chose the group ID:
```
dscl . -list /Users UniqueID | awk '{print $2}' | sort -n
```
Finally, run by replacing the placeholders:
```
sudo dscl . -create /Users/{UserName}
sudo dscl . -create /Users/{UserName} UserShell /bin/bash
sudo dscl . -create /Users/{UserName} UniqueID {UserID}
sudo dscl . -create /Users/{UserName} PrimaryGroupID {GroupID}
sudo dscl . -create /Users/{UserName} NFSHomeDirectory /Users/{UserName}
```
Ensure a home folder is created for the user:
```
sudo mkdir /Users/{UserName}
sudo chown {User}:{GroupName} /Users/{UserName}
```
## Creating Default Keychain for the Build User
Since the build user will not log into the OSX machine, a default keychain will never be created.\
This could cause build and/or code sign issues (especially when using fastlane).
To create a default keychain for the build user, switch to the build user in the terminal:
```
sudo su {Username}
```
Execute commands as the build user:
```
security create-keychain -p {KeychainPassword} login.keychain
security default-keychain -s login.keychain
```
This creates new keychain called `login.keychain`and makes it default for the build user.\
The security command line tool has a bug and does not add the new keychain to the list of available keychains. To fix this, call:
```
security list-keychains -d user -s {Keychain}
```
Proceed with the rest of the setup. To switch back to the previous user type:
```
exit
```
## Logging Remotely with the Build User
Remote logging is required. To log remotely with the newly created build user and ensure the user can log remotely:
```
sudo systemsetup -setremotelogin on
sudo dseditgroup -o edit -a {UserName} -t user com.apple.access_ssh
```
Create an SSH key pair to use for remote logging.
If an SSH key pair does not exist, then create one by executing:
```
ssh-keygen -m PEM -t rsa -C "build machine key" -f "buildMachine_rsa"
```
For increased security, it is recommended to associate a passphrase to the private key.
The command creates two files:
* buildMachine\_rsa - This is the private key. Keep it safe and do not share it with anyone.
* buildMachine\_rsa.pub - This is the public key.
To copy the private key to a secure machine, use `scp`. This command executes copy over SSH; run:
```
scp /path-to-buildMachine_rsa/ username@host:/path-to-location-on-secure-machine
```
To create a `authorized_keys` file. It lists all keys that can be used to log remotely with a given user:
```
sudo su {UserName}
mkdir ~/.ssh
cat buildMachine_rsa.pub >> ~/.ssh/authorized_keys
chmod 644 ~/.ssh/authorized_keys
exit
```
Use the private key to log to the machine remotely using the newly created user:
```
ssh {UserName}@{host} -i {path-to-private-key}
```
# Network Firewalls Mac Mini Connect
Source: https://docs.macstadium.com/iaas/cisco-firewalls/network-firewalls-mac-mini-connect
Connect to a firewall-protected Mac mini via Screen Sharing, VNC, or SSH. Find MacStadium Portal credentials and connect from macOS or Windows.
**For customers with a firewall**
If you have an account that includes a firewall, visit the "[Connect to your Cloud (VPN)](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn)" page.
Getting connected to a dedicated Mac mini at MacStadium is simple, because the server is pre-configured to be controlled with VNC or SSH.
## Finding Your Login Credentials After Signup
Use initial login credentials after checkout. Follow these steps to access them:
1. Log into the [Portal account](https://portal.macstadium.com/login). These are the same credentials which were created or used during the checkout process.
2. Locate a ticket titled "Installation"
3. The ticket contains the following information: IP address, username, and password (needed to access the machine)
## Connecting from macOS with Screen Sharing
Connecting to the MacStadium Mac's desktop from a Mac is very simple because a VNC client is included with macOS.
1. Input your machine's IP address into Safari replacing HTTP with VNC (e.g. vnc://xxx.xxx.xxx.xxx)
2. Apple Screen Sharing app will launch and request the machine's username and password
3. The login screen appears - enter your password one more time
## Connecting via VNC from Windows
Connecting to the MacStadium Mac's desktop is simple from Windows but requires a VNC client. MacStadium recommends Real VNC Viewer, which is free to use.
1. Download [Real VNC viewer](https://www.realvnc.com/en/connect/download/viewer/windows/)
2. Install and run
3. Use the IP address from the installation ticket
4. Use the username and password from the installation ticket
5. At the macOS login screen, enter the password one more time
## Connecting from Windows 10 via SSH
Connecting to your MacStadium Mac terminal via SSH is simple with Windows 10's native SSH command.
1. Go to the search bar and type "CMD" and open Command Prompt
2. Into the prompt, enter: ssh username\@your-ip-address - where the username and IP address are the first login credentials you received after sign up
3. Enter the password for your machine
# Network Firewalls: Overview
Source: https://docs.macstadium.com/iaas/cisco-firewalls/network-firewalls-overview
MacStadium offers a variety of Cisco(R) firewalls to protect the cloud environment. The portfolio includes several physical and virtual appliance choices.
## About
MacStadium offers a variety of Cisco® firewalls to protect the cloud environment. The portfolio includes several physical and virtual appliance choices, which exceed all security and performance requirements.
## Overview
Cisco Firepower and Cisco Secure Firewall ASA Virtual offerings deliver scalable VPN capability to access MacStadium resources, as well as, protect workloads against increasingly complex threats with world-class security controls.
To provision Firewalls in the MacStadium account, please [contact sales](https://www.macstadium.com/contact/sales).
The following capabilities are available with Cisco firewalls:
* Access and manage the firewall as the root user (root access).
* Use [Cisco AnyConnect](https://www.cisco.com/c/en/us/support/security/anyconnect-secure-mobility-client/tsd-products-support-series-home.html) for secure remote user access.
* Filter any Internet and internal traffic real-time. For example, pass traffic from selected IPs or IP ranges (like a Jenkins master) and block all other traffic.
* Connect local infrastructure to the MacStadium private cloud through secure remote network or site-to-site encrypted Virtual Private Network (VPN) tunnels.
* Connect a public cloud, such as AWS, Azure, or Google Cloud, to the MacStadium private cloud through secure remote network or site-to-site encrypted Virtual Private Network (VPN) tunnels.
* Perform packet inspection, port blocking, and breach protection.
* Configure high availability and failover.
* Limit access to approved users to ensure complete access control.
## Getting Started
Contact [MacStadium Sales](https://www.macstadium.com/contact/sales) for more information.
## Standard Configurations
| Feature | ASAv 10 | ASAv 30 | Firepower 2130 |
| --------------------------------------------------- | -------- | ------- | -------------- |
| Appliance Form Factor | Virtual | Virtual | Physical |
| Stateful inspection throughput max | 1 Gbps | 2 Gbps | 5.4 Gbps |
| Stateful inspection throughput max (multi-protocol) | 1 Gbps | 2 Gbps | 5.4 Gbps |
| IPsec VPN throughput | 750 Mbps | 2 Gbps | 1.9 Gbps |
| Connections per second | 60,000 | 200,000 | 30,000 |
| Concurrent sessions | 100,000 | 500,000 | 2,000,000 |
| IPsec VPN peers | 250 | 750 | 7,500 |
## Custom Hardware or Hybrid Solutions
To host a firewall in a MacStadium data center, contact MacStadium Sales to discuss requirements, available options, and involvement from the MacStadium engineering team.
You can access any enabled firewall add-ons from the MacStadium Portal under the **Add-Ons** tab in the details.
## Other options
Based on your specific requirements, you may choose to forgo the available Cisco ASAv and ASA options and implement another solution, such as the built-in OS X firewall or a third-party software firewall.
MacStadium does not provide assistance with the setup, management, and troubleshooting of these solutions. MacStadium is not responsible for any security risks incurred by such implementations.
## Available Locations
Available in: Atlanta, Dublin, Las Vegas
# MacStadium network onboarding form for new customers
Source: https://docs.macstadium.com/iaas/cisco-firewalls/network-onboarding-form
The Network Onboarding Form collects the network provisioning details our platform team needs to configure access to your MacStadium cloud environment.
## Overview
The Network Onboarding Form collects the network provisioning details our platform team needs to configure access to your MacStadium cloud environment. All new customers must complete and submit this form before network setup can begin.
Network Onboarding Form
The [form](https://github.com/macstadium/macstadium-docs/blob/a7b0d9ec76e7b2d7c0eafb67d33f5cbc26ed33e3/iaas/cisco-firewalls/MacStadium%20Network%20Services%20Onboarding%20Form%20\(2026-03-06\).pdf) covers your cloud service selection (Bare Metal, Orka, or Private Cloud), preferred connection method, and any VPN or firewall parameters specific to your environment. Submit the completed form to your account team or via a support ticket in the customer portal.
# Prepare the VPN Configuration for Input into Cisco ASA/ASAv
Source: https://docs.macstadium.com/iaas/cisco-firewalls/prepare-the-vpn-configuration-for-input-into-cisco-asaasav
Hub for MacStadium Cisco ASA/ASAv VPN setup: links to the IP Plan, VPN connection guide, SSH access, firewall login, and site-to-site VPN config articles.
## General Resources
### [IP Plan](/macstadium/macstadium-overview/ip-plan)
This is an overview of the IP Plan, which outlines networking details.
### [Connect via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn)
This is the first connection needed. It is a prerequisite for most operations.
### [Connect via SSH](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-ssh)
This is a way to gain access for scripted processes, such as provisioning VMs and\
automating operations with tools such as Ansible and Packer.
## Accessing the Firewall Directly
### [Cisco Firewall Overview](/iaas/cisco-firewalls/network-firewalls-overview)
This is used to protect the environment; MacStadium deploys the private cloud with a dedicated\
Cisco firewall, which offers the highest quality security for the entire environment.
### [Logging into Your Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall)
This is a guide to access and configure firewalls.
# Connect third-party clouds to MacStadium
Source: https://docs.macstadium.com/iaas/connecting-to-other-clouds/other-clouds
Connect AWS, Azure, GCP, or a private cloud to MacStadium via IPsec site-to-site VPN. Covers shared files, cloud infrastructure, and hybrid CI/CD setups.
## Connect a Third-Party Cloud to Your MacStadium Environment If
You need to share files between the two clouds.
You need to share the cloud infrastructure.
You need to access the virtual machines from one cloud on the other.
You need to run a more complex CI/CD setup where the macOS part of the pipeline is hosted in\
MacStadium and the remaining pipeline is hosted in another cloud.
## Step 1 Setup Third-Party Site-to-Site Config
Select the third-party provider you would like to connect your Mac Cloud to, and\
follow the setup instructions provided.
* [AWS Networking Setup](/iaas/aws/aws-networking-setup)
* [Azure Networking Setup](/iaas/azure/azure-networking-setup)
* [Google Cloud Platform Networking Setup](/iaas/google-cloud-platform/google-cloud-networking-setup)
* [Private Cloud Networking Setup](/iaas/connecting-to-other-clouds/private-cloud-networking-setup)
## Step 2 Prepare for MacStadium (Cisco ASA/ASAv) Config
Follow the associated guide provided below as you prepare the VPN configuration for input\
into the Cisco ASA/ASAv.
* [AWS Cisco Config Guide](/iaas/aws/aws-vpn-config-for-cisco-asaasav)
* [Azure Cisco Config Guide](/iaas/azure/azure-vpn-config-for-cisco-asaasav)
* [GCP Cisco Config Guide](/iaas/google-cloud-platform/gcp-vpn-config-for-cisco-asaasav)
## Step 3 Setup MacStadium Site-to-Site Config
Now you will need to configure the MacStadium end of things.
Configure MacStadium's End of the Site-to-Site VPN
## Step 4 (Optional) Verify Connection
* [Verify AWS Connection](/iaas/aws/verify-aws)
* [Verify Azure Connection](/iaas/azure/verify-azure)
* [Verify GCP Connection](/iaas/google-cloud-platform/verify-gcp)
# Private Cloud Networking Setup
Source: https://docs.macstadium.com/iaas/connecting-to-other-clouds/private-cloud-networking-setup
Connect your private cloud to MacStadium via IPsec site-to-site VPN: Cisco ASA/ASAv NAT exemption, access-list rules, and crypto map configuration.
Because of the highly customizable nature of on-premises private clouds, this guide is not precise but aims to provide general guidelines instead.
If you need to establish one-time or temporary access to your MacStadium cloud from a single virtual or physical machine, you can connect via VPN using Cisco AnyConnect. For more information, see [Connect to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
If you need to connect an entire private cloud to your MacStadium cloud through a stable, persistent connection, you need to establish an IPsec site-to-site VPN between the two clouds.
To create a stable IPSec site-to-site VPN between your two clouds, you need to:
1. Check the [software version and model](/iaas/cisco-firewalls/checking-the-firewall-version) of the Cisco ASA/ASAv device of your MacStadium cloud.
2. Configure your private cloud to connect to your MacStadium cloud. You might need to configure one or more of the following:
* Provide the public endpoint of your MacStadium cloud. Usually, this is the public network IP listed for the FW1-Outside network in Appendix B of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* Enable policy-based routing between your private cloud and the internal private network of your MacStadium cloud (by default, the Private-1 network). Usually, this is the private network host and range listed in Appendix A of the IP Plan.
* Enable inbound traffic to your private cloud.
3. Set up the Cisco ASA/ASAv device of your MacStadium cloud. You might need to configure one or more of the following rules:
* A nat exemption rule for traffic between the two clouds. It might need to allow traffic from the private cloud to the private network and the outside interface of your MacStadium cloud. By default, these are respectively the Private-1 and Outside networks listed in Appendix A of the IP Plan.
* access-list rules permitting traffic from the private cloud to the public endpoint of your MacStadium cloud. By default, this is the FW1-Outside network listed in Appendix B of the IP Plan.
* A crypto map rule that maps traffic between the two clouds. Usually, you would need to map to the outside interface of your MacStadium cloud. By default, this is the Outside network listed in Appendix A of the IP Plan.
* IPSec and IKE policies.
* tunnel-group rules that point to the private cloud you want to connect to your MacStadium cloud.
You need to prepare these settings based on your Cisco ASA/ASAv software and model. For more information about how to configure each aspect of your Cisco firewall, see [Cisco Documentation: Configuration Guides](https://www.cisco.com/c/en/us/support/security/asa-5500-series-next-generation-firewalls/products-installation-and-configuration-guides-list.html).
## See also
* [Cisco Documentation: Navigating the Cisco ASA Series Documentation](https://www.cisco.com/c/en/us/td/docs/security/asa/roadmap/asaroadmap.html)
* [Cisco Documentation: Managing Site-to-Site VPNs: The Basics](https://www.cisco.com/c/en/us/td/docs/security/security_management/cisco_security_manager/security_manager/4-1/user/guide/CSMUserGuide_wrapper/vpchap.pdf)
* [Cisco Documentation: Cisco ASA Series Syslog Messages](https://www.cisco.com/c/en/us/td/docs/security/asa/syslog/b_syslog.html)
* [Logging into Your Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall)
* [AWS Networking Setup](/iaas/aws/aws-networking-setup)
* [Azure Networking Setup](/iaas/azure/azure-networking-setup)
* [Google Cloud Networking Setup](/iaas/google-cloud-platform/google-cloud-networking-setup)
# Site-to-Site VPN Config
Source: https://docs.macstadium.com/iaas/connecting-to-other-clouds/site-to-site-vpn-config
Apply a prepared VPN config to the MacStadium Cisco ASA/ASAv via ASDM-IDM. Final step after configuring the cloud side and preparing the ASA config.
## Prerequisites
***Verify that you have configured the non-MacStadium side of the VPN connection.***
For more information, see:
* [Setting Up the AWS Side of the Site-to-Site VPN](/iaas/aws/site-to-site-vpn-configuration-with-aws)
* [Setting Up the Azure Side of the Site-to-Site VPN](/iaas/azure/site-to-site-vpn-configuration-with-azure)
* [Setting Up the GCP Side of the Site-to-Site VPN](/iaas/google-cloud-platform/site-to-site-vpn-configuration-with-gcp)
***Verify that you have prepared the configuration.***
For more information, see [Prepare the VPN Configuration for Input into Cisco ASA/ASAv](/iaas/cisco-firewalls/prepare-the-vpn-configuration-for-input-into-cisco-asaasav).
***Verify that you are connected via VPN to your MacStadium private cloud.***
For more information about how to connect to the VPN, see [Connecting to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
## Process
1. Run Cisco ASDM-IDM and log in
2. For more information about how to log in to your firewall, see [Logging in to Your Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall)
3. In the Cisco ASDM-IDM application toolbar, select **Tools > Command Line Interface**
4. Select Multiple Line
5. Type configure terminal, press Enter and paste the contents of the prepared VPN configuration
6. For more information about this command, see [Cisco Documentation: configure terminal](https://www.cisco.com/c/m/en_us/techdoc/dc/reference/cli/n5k/commands/configure-terminal.html)
7. Click Send
8. Verify connection (*optional*)
# GCP-to-MacStadium VPN troubleshooting
Source: https://docs.macstadium.com/iaas/google-cloud-platform/gcp-troubleshooting
If you encounter any issues during or after the configuration of your site-to-site VPN connection between Google Cloud Platform (GCP) and MacStadium.
If you encounter any issues during or after the configuration of your site-to-site VPN connection between Google Cloud Platform (GCP) and MacStadium, check this list of common issues and troubleshooting instructions.
* Unrecognized interface during the Cisco ASA/ASAv configuration
* The tunnel is connected but there's no traffic between GCP and MacStadium
* There's traffic from GCP to MacStadium but you cannot access GCP from MacStadium
## Unrecognized interface during the Cisco ASA/ASAv configuration
Sometimes, the command line interface might return `ERROR: unable to find interface "outside"`. The command-line interface might be case-sensitive and you might need to preserve the capitalization of the MacStadium network configuration as provided in the [IP Plan](/macstadium/macstadium-overview/ip-plan).
1. Clean up the ASA configuration.
* For more information, see Cleaning up the ASA/ASAv configuration.
2. Rename outside in your configuration to the precise name of the outside interface of your Cisco ASA/ASAv device. By default, this is the Outside network.
* For more information, see [GCP VPN Config for Cisco ASA/ASAv](/iaas/google-cloud-platform/gcp-vpn-config-for-cisco-asaasav).
3. Re-run the complete configuration in Cisco ASDM-IDM.
* For more information, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
## The tunnel is connected but there's no traffic between GCP and MacStadium
If GCP shows that the tunnel is Established but there is no visibility and connectivity between the two clouds, it might be because of some common mistakes when preparing the configuration. Check for the following in the site-to-site VPN configuration. For more information, see [GCP VPN Config for Cisco ASA/ASAv](/iaas/google-cloud-platform/gcp-vpn-config-for-cisco-asaasav).
* Verify that your \{ shared\_key } is correct. The \{ shared\_key } in the configuration must match the key set for the VPN connection.
* Verify that you've replaced \{ macstadium\_network\_address } and \{ macstadium\_network\_mask } with the correct values for the internal, private network of your MacStadium private cloud. By default, this is the Private-1 network.
* You can find the networking information for this network in Appendix A of your [IP Plan](/macstadium/macstadium-overview/ip-plan).
* Verify that you've configured the NAT exemption rule properly.
* The host and subnet mask required for ONPREM-NET are the host and mask for the internal, private network of your MacStadium private cloud. By default, this is the Private-1 network. You can find the networking information for this network in Appendix A of your IP Plan.
* The host and subnet mask required for GCP-NET are the host and mask for your GCP virtual network. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the /16 notation converts to a 255.255.0.0 subnet mask).
* The values in the brackets after nat must be the name of the internal, private network of your MacStadium private cloud, followed by the name of the outside interface of your Cisco ASA/ASAv device. By default, these are Private-1 and Outside, respectively.
* You can find the names of these networks in Appendix A of your IP Plan.
To resolve any of the listed common problems with the Cisco ASA/ASAv configuration, complete the following steps:
1. Clean up the firewall configuration.
* For more information, see Cleaning up the ASA/ASAv configuration.
2. Make the necessary changes to the configuration.
* For more information, see [GCP VPN Config for Cisco ASA/ASAv](/iaas/google-cloud-platform/gcp-vpn-config-for-cisco-asaasav).
3. Re-run the complete configuration in Cisco ASDM-IDM.
* For more information, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
## There's traffic from GCP to MacStadium but you cannot access GCP from MacStadium
Sometimes, you might be able to establish an SSH connection from GCP to MacStadium but you might not be able to see or access GCP from MacStadium. This might be due to any of the following issues:
* The GCP firewall is not configured to allow ingress traffic.
For information about how to enable ingress traffic, see [Google Cloud Documentation: Configuring firewall rules > Example configurations](https://cloud.google.com/vpn/docs/how-to/configuring-firewall-rules#example_configurations).
* Your GCP instances don't allow OS login.
For more information about user login on GCP instances, see [Google Cloud Documentation: Setting up and configuring OS Login](https://cloud.google.com/compute/docs/instances/managing-instance-access).
## Troubleshooting
### Cleaning up the ASA/ASAv configuration
Sometimes, you might need to clean up the Cisco ASA/ASAv configuration and start over.
1. Verify that you are connected via VPN to your MacStadium private cloud.
For more information about how to connect to the VPN, see [Connecting to Your Cloud (via VPN)](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
3. For more information about how to log in to your firewall, see [Logging into Your Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
In the Cisco ASDM-IDM application toolbar, select **Tools > Command Line Interface**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line.
5. Run the following commands one by one, clicking Send in between. Replace the placeholders with their respective values. Use Table 1: Placeholders for reference.
```
clear configure tunnel-group { gcp_vpn_ip }
clear configure group-policy gcp
clear configure access-list gcp-in
clear configure access-list gcp-acl
clear configure access-list gcp-filter
clear configure crypto map gcp-vpn-map
clear configure crypto ipsec ikev2 ipsec-proposal gcp
no nat ({ macstadium_network_name },{ macstadium_outside_interface }) 1 source static ONPREM-NET ONPREM-NET destination static GCP-NET GCP-NET
no object-group network GCP-NET
no object-group network ONPREM-NET
```
### Table 1: Placeholders
| Placeholder | Description | Example |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `{ gcp_vpn_ip }` | The public IP address of the cloud VPN gateway in GCP. | `192.168.0.0` |
| `{ macstadium_network_name }` | The name of the private network in MacStadium that needs to be accessed by GCP. You can find the information about your private network in Appendix A of the IP Plan. | `Private-1` |
| `{ macstadium_outside_interface }` | The name of the outside interface of your Cisco ASA/ASAv device. You can find the information about your outside interface in Appendix A of the IP Plan. | `Outside` |
## More troubleshooting by Google
For more detailed troubleshooting instructions, see [Google Cloud Documentation: Cloud VPN Troubleshooting](https://cloud.google.com/vpn/docs/support/troubleshooting).
## More troubleshooting by Cisco
For more detailed troubleshooting instructions, see [Cisco Documentation: IPsec Troubleshooting](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html).
# GCP VPN Config for Cisco ASA/ASAv
Source: https://docs.macstadium.com/iaas/google-cloud-platform/gcp-vpn-config-for-cisco-asaasav
Configure your Cisco ASA/ASAv for a GCP-MacStadium VPN using the provided template. Fill in GCP and MacStadium network values, then apply the config.
After you have created your site-to-site VPN connection in Google Cloud Platform (GCP), you need to configure your Cisco firewall to recognize the connection and let traffic into your MacStadium private cloud.
You can use the configuration template provided below and fill in the missing information. You need to provide data from both GCP and MacStadium.
1. Configuration template
2. Fill in the configuration blanks
* Get the configuration values
* Complete the template
## Configuration template
Unless you have extensive experience with GCP and ASA/ASAv configurations, use the configuration from the template. Otherwise, your site-to-site VPN might not work as expected.
This is a template configuration that you can use to complete the setup of your GCP-MacStadium site-to-site VPN connection.
```
! #1: Placeholders
!
! { gcp_network_address } - The address of the GCP local network that needs to have access to MacStadium.
! { gcp_network_mask } - The subnet mask of the GCP local network that needs to have access to MacStadium.
! { gcp_vpn_ip } - The public IP address of the cloud VPN gateway in GCP.
! { macstadium_network_name } - The name of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1.
! { macstadium_network_address } - The IP address of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1.
! { macstadium_network_mask } - The subnet mask of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1.
! { macstadium_public_ip } - The IP address of the public network of your MacStadium private cloud. By default, this is FW1-Outside.
! { macstadium_outside_interface } - The name of the outside interface of your Cisco ASA/ASAv device. By default, this is Outside.
! { shared_key } - The IPSec pre-shared key used when creating the VPN connection in GCP.
!
! #2: NAT exemption
!
! The name "GCP-NET" must be unique for the Cisco ASA/ASAv device.
!
object-group network GCP-NET
description GCP Virtual Network
network-object { gcp_network_address } { gcp_network_mask }
! The name "ONPREM-NET" must be unique for the Cisco ASA/ASAv device.
object-group network ONPREM-NET
description OnPrem Network
network-object { macstadium_network_address } { macstadium_network_mask }
! The names "gcp-in", "gcp-acl", and "gcp-filter" must be unique for the Cisco ASA/ASAv device.
access-list gcp-in extended permit ip host { gcp_vpn_ip } host { macstadium_public_ip }
access-list gcp-acl extended permit ip any4 object-group GCP-NET
access-list gcp-filter extended permit ip object-group GCP-NET object-group ONPREM-NET
nat ({ macstadium_network_name },{ macstadium_outside_interface }) 1 source static ONPREM-NET ONPREM-NET destination static GCP-NET GCP-NET
! #3: IKE & IPSec configuration
!
! The name "gcp" must be unique for the Cisco ASA/ASAv device.
crypto ipsec ikev2 ipsec-proposal gcp
protocol esp encryption aes-256
protocol esp integrity sha-1
! The name "gcp-vpn-map" must be unique for the Cisco ASA/ASAv device.
crypto map gcp-vpn-map 1 match address gcp-acl
crypto map gcp-vpn-map 1 set pfs group14
crypto map gcp-vpn-map 1 set peer { gcp_vpn_ip }
crypto map gcp-vpn-map 1 set ikev2 ipsec-proposal gcp
crypto map gcp-vpn-map interface { macstadium_outside_interface }
crypto ikev2 policy 100
encryption aes-256
integrity sha512
group 14
prf sha
lifetime seconds 36000
exit
crypto ikev2 enable { macstadium_outside_interface }
crypto ipsec security-association lifetime seconds 10800
crypto ipsec security-association replay window-size 128
crypto ipsec security-association pmtu-aging infinite
crypto isakmp identity address
crypto isakmp disconnect-notify
no crypto isakmp nat-traversal
crypto ipsec df-bit clear-df Outside
group-policy gcp internal
group-policy gcp attributes
vpn-filter value gcp-filter
vpn-tunnel-protocol ikev2
tunnel-group { gcp_vpn_ip } type ipsec-l2l
tunnel-group { gcp_vpn_ip } general-attributes
default-group-policy gcp
tunnel-group { gcp_vpn_ip } ipsec-attributes
isakmp keepalive threshold 10 retry 3
ikev2 remote-authentication pre-shared-key { shared_key }
ikev2 local-authentication pre-shared-key { shared_key }
```
## Fill in the configuration blanks
You need to manually replace the placeholders in the configuration template with the values for your GCP and MacStadium configurations.
### Get the configuration values
**\{ gcp\_network\_address }**
This is the IP address of the GCP local network that needs to have access to MacStadium.
1. Verify that you're logged into the GCP console and you are working in the correct project.\\
![GCP console project selector in the toolbar]()
2. From the GCP console sidebar, scroll to the Networking section and select Hybrid Connectivity > VPN.\\
![GCP sidebar with Hybrid Connectivity VPN option highlighted]()
3. Select Cloud VPN Gateways.
4. Locate the gateway used by your GCP-MacStadium tunnel and note the value for Region.\\
![GCP Cloud VPN Gateways list showing gateway region and VPC network]()
5. Click the value listed under VPC network.
* The GCP console redirects you to the list of subnets for the selected network.
6. In the list of subnets, locate the one matching the region you noted in Step 4.
7. From the respective IP address ranges field, use the IP address without the bit notation at the end (e.g. /16).
**\{ gcp\_network\_mask }**
This is the subnet mask the GCP local network that needs to have access to MacStadium.
1. Verify that you're logged into the GCP console and you are working in the correct project.\\
![GCP console project selector in the toolbar]()
2. From the GCP console sidebar, scroll to the Networking section and select Hybrid Connectivity > VPN.\\
![GCP sidebar with Hybrid Connectivity VPN option highlighted]()
3. Select Cloud VPN Gateways.
4. Locate the gateway used by your GCP-MacStadium tunnel and note the value for Region.\\
![GCP Cloud VPN Gateways list showing gateway region and VPC network]()
5. Click the value listed under VPC network.
* The GCP console redirects you to the list of subnets for the selected network.
6. In the list of subnets, locate the one matching the region you noted in Step 4.
7. From the respective IP address ranges field, use the bit notation at the end (e.g. /16) and convert it to a subnet mask. You can use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
**\{ gcp\_vpn\_ip }**
This is the public IP address of the cloud VPN gateway in GCP.
1. Verify that you're logged into the GCP console and you are working in the correct project.\\
![GCP console project selector in the toolbar]()
2. From the GCP console sidebar, scroll to the Networking section and select Hybrid Connectivity > VPN.\\
![GCP sidebar with Hybrid Connectivity VPN option highlighted]()
3. Select Cloud VPN Gateways.
4. Locate the gateway used by your GCP-MacStadium tunnel and use the value listed under IP address.\\
![GCP Cloud VPN Gateways list showing gateway IP address field]()
**\{ macstadium\_network\_name }**
This is the name of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1.
* You can find the information about your private network in Appendix A of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
**\{ macstadium\_network\_address }**
This is the IP address of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1.
**\{ macstadium\_network\_mask }**
This is the subnet mask of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1.
**\{ macstadium\_public\_ip }**
This is the IP address of the public network of your MacStadium private cloud. By default, this is FW1-Outside.
**\{ macstadium\_outside\_interface }**
This is the name of the private network in MacStadium that needs to be accessed by GCP. By default, this is Outside.
**\{ shared\_key }**
This is the IPSec pre-shared key used when creating the VPN connection in GCP. You must have this key saved separately.
## Complete the template
1. Copy the template into a text editing tool.
2. Replace all placeholders with their respective values.
3. Delete the remaining commented lines to clean up the template. Commented lines are indicated by ! at the beginning of the line.
4. Save your changes.
## Next steps
If you are ready to feed the complete configuration into your Cisco ASA/ASAv, see [Setting Up the MacStadium Side of the Site-to-Site VPN](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
# Google Cloud Networking Setup
Source: https://docs.macstadium.com/iaas/google-cloud-platform/google-cloud-networking-setup
To establish a stable, persistent connection between a Google Cloud Platform (GCP) private cloud and your MacStadium private cloud, you need to configure.
To establish a stable, persistent connection between a Google Cloud Platform (GCP) private cloud and your MacStadium private cloud, you need to configure a policy-based IPsec site-to-site VPN between the two clouds.
Currently, you can create only a classic VPN connection with policy-based routing from GCP to MacStadium. It consists of one tunnel and one interface and does not provide high availability. For more information about this option, see [Google Cloud Documentation: Classic VPN](https://cloud.google.com/vpn/docs/how-to/choosing-a-vpn#classic-vpn).
To create a site-to-site VPN from your GCP private cloud to your MacStadium private cloud, you need to go through the following high-level steps:
1. Log into GCP
2. Create the VPN connection
## Log into GCP
1. Log in to the GCP console with your credentials.
2. In the toolbar at the top, make sure that you're working with the correct project.\\
![GCP console toolbar with project selector]()
## Create the VPN connection
From the GCP console sidebar, scroll to the Networking section and select **Hybrid Connectivity > VPN**.
![GCP sidebar with Hybrid Connectivity VPN option highlighted]()
Classic VPN connections in GCP consist of a gateway and tunnel. You can create a gateway and a tunnel at once or you can add a new tunnel to an existing gateway.
## Create gateway and tunnel
If you don't have a classic VPN gateway that you want to use, complete the following steps.
1. If you don't have any VPNs created yet, click Create VPN connection.
2. If you have one or more VPNs created, click + VPN SETUP WIZARD.
3. Select Classic VPN and click Continue.
* The High-availability (HA) VPN is currently not supported as an option. For more information about the available options, see [Google Cloud Documentation: Choosing a VPN option](https://cloud.google.com/vpn/docs/how-to/choosing-a-vpn).
4. In the Google Compute Engine VPN gateway section, provide Name and Description.
5. For Network, select the GCP network that needs to be able to access MacStadium.
6. Select Region.
* For more information about this setting, see [Google Cloud Documentation: Regions and Zones](https://cloud.google.com/compute/docs/regions-zones).
7. Select or create a reserved IP address for the connection.
* You will need this IP address when you configure the MacStadium side of the tunnel.
8. In the Tunnels section, provide Name and Description.
9. For Remote peer IP address, provide the IP address of the public network listed in Appendix B of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* By default, this is the FW1-Outside network.
10. For IKE version, verify that IKEv2 is selected.
11. Provide or generate an IKE pre-shared key.
Keep a record of the pre-shared key. You will need it later.
12. For Routing options, select Policy-based.
13. For Remote network IP ranges, provide the IP range in CIDR notation of the private network listed in Appendix A of the IP Plan.
* By default, this is the Private-1 network.
* For more information about CIDR notations, see [Understanding IP Addresses, Subnets, and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation). You can also use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
14. (Optional) Select one or more GCP subnetworks to reduce latency between your GCP private cloud and your MacStadium private cloud.
* For more information, see [Google Cloud Documentation: Networks and subnets](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets).
15. (Optional) Provide one or more IP ranges within your GCP local network that needs to access MacStadium.
16. Click Done.
17. Click Create.
After the creation is complete, the VPN tunnel status is: First handshake.
### Example: Create gateway and tunnel
This image shows a sample configuration for the VPN gateway and tunnel.
![GCP VPN gateway and tunnel configuration form with sample settings]()
## Add a new tunnel to an existing gateway
If you have an existing classic VPN gateway that you want to use for the connection, complete the following steps.
1. Select Cloud VPN Tunnels and click Create VPN tunnel.\\
![GCP Cloud VPN Tunnels tab with Create VPN tunnel button]()
2. Select the VPN gateway that you want to use and click Continue.
Make sure that you have selected a classic VPN gateway. High-availability gateways are not supported.
3. Provide Name.
4. (Optional) Provide Description.
5. For Remote peer IP address, provide the IP address of the public network listed in Appendix B of the IP Plan.
* By default, this is the FW1-Outside network.
6. For IKE version, verify that IKEv2 is selected.
7. Provide or generate an IKE pre-shared key.
Keep a record of the pre-shared key. You will need it later.
8. For Routing options, select Policy-based.
9. For Remote network IP ranges, provide the IP range in CIDR notation of the private network listed in Appendix A of the IP Plan.
* By default, this is the Private-1 network.
* For more information about CIDR notations, see [Understanding IP Addresses, Subnets, and CIDR Notation for Networking](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation). You can also use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
10. (Optional) Select one or more GCP subnetworks to reduce latency between your GCP private cloud and your MacStadium private cloud.
* For more information, see [Google Cloud Documentation: Networks and subnets](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets).
11. (Optional) Provide one or more IP ranges within your GCP local network that needs to access MacStadium.
12. Click Create.
After the creation is complete, the VPN tunnel status is: First handshake.
### Example: Create the VPN gateway and tunnel
This image shows a sample configuration for the VPN connection.
![GCP VPN tunnel configuration form showing sample settings for an existing gateway]()
## Ensure that the GCP firewall allows ingress traffic
Based on your requirements, you might need to enable ingress traffic from MacStadium to GCP in the GCP firewall. For more information, see [Google Cloud Documentation: Configuring firewall rules > Example configurations](https://cloud.google.com/vpn/docs/how-to/configuring-firewall-rules#example_configurations).
## Next steps
If you are ready to proceed with the MacStadium side of the configuration, see [Preparing the VPN Configuration for Input into Cisco ASA/ASAv](/iaas/google-cloud-platform/gcp-vpn-config-for-cisco-asaasav).
# Site-to-Site VPN Configuration with GCP
Source: https://docs.macstadium.com/iaas/google-cloud-platform/site-to-site-vpn-configuration-with-gcp
The goal of this documentation is to update the Site-to-Site VPN configuration with GCP and add specific configuration details for the ASA feature TCP.
## Overview
The goal of this documentation is to update the Site-to-Site VPN configuration with GCP and add specific configuration details for the ASA feature TCP State-bypass, which is required in HA VPN scenarios.
## Google Cloud Networking Setup
To establish a stable, persistent connection between a Google Cloud Platform (GCP) private cloud and the MacStadium private cloud, configuration must be set between an IPsec Site-To-Site VPN, between the two clouds. Currently, for connectivity between MacStadium and GCP, there are two options:
* **Classic VPN** with policy-based which consists of a single VPN tunnel, with a single external IP address and a single interface. This option does not provide high availability.
* **HA VPN** with dynamic routing (BGP) which provides high availability with multiple VPN tunnels, interfaces, and external IP addresses. This guide is based on the GCP One peer VPN device with one IP address topology available at: Google Cloud Documentation: 1 Peer - 1 Address. HA VPN must use dynamic routing with BGP. Classic VPN remains an option for connecting to MacStadium firewalls that do not run BGP. For more information about general Google Cloud VPN, see Google Cloud Documentation: [Cloud VPN Overview](https://cloud.google.com/network-connectivity/docs/vpn/concepts/overview).
The feature TCP State Bypass in the ASA / ASAv firewall is required for HA VPN only, and is configured to allow asynchronous routing between the separate VPN tunnels.
To create a site-to-site VPN from your GCP private cloud to your MacStadium private cloud, you need to go through the following high-level steps:
1. Log into GCP\\
![GCP console project selector in the toolbar]()
2. Create the VPN connection\\
![GCP sidebar with Hybrid Connectivity VPN option highlighted]()
Classic and HA VPN connections in GCP require a Cloud VPN Tunnel and a Cloud VPN Gateway. Both elements can be at once or you can add a new Cloud VPN Tunnel to an existing Cloud VPN Gateway.
## Create VPN Gateway and Tunnel
To create a new VPN Gateway, complete the following steps:
1. If the VPNs are not created yet, then click CREATE VPN CONNECTION.
2. If one or more of the VPNs are created, then click +VPN SETUP WIZARD.
3. Select Classic VPN or High-availability (HA) VPN.
4. Click Continue.
## Classic VPN Configuration
1. In the GCP VPN gateway section, provide Name and Description.
2. For Network, select the GCP network that needs to be able to access MacStadium.
3. Select Region.
4. Select or create a reserved IP address for the connection. This IP address is needed when you configure the MacStadium side of the tunnel.
5. In the Tunnels section, provide Name, and Description.
6. For Remote peer IP address, provide the IP address of the public network listed in Appendix B of the IP Plan. By default, this is the FW1-Outside network.
7. For IKE version, verify that IKEv2 is selected.
8. Provide or generate an IKE pre-shared key.
* Keep a record of the pre-shared key. It is needed later.
9. For Routing options, select Policy-based.
10. For Remote network IP ranges, provide the IP range in CIDR notation of the private network listed in Appendix A of the [IP Plan](/macstadium/macstadium-overview/ip-plan). By default, this is the Private-1 network. For more information about CIDR notations, see Understanding IP Addresses, Subnets, and CIDR Notation for Networking. You can also use a CIDR calculator such as this CIDR/Netmask Lookup Tool.
11. (Optional) Select one or more GCP subnetworks to reduce latency between your GCP private cloud and your MacStadium private cloud.
* For more information, see Google Cloud Documentation: Networks and subnets.
12. (Optional) Provide one or more IP ranges within your GCP local network that needs to access MacStadium.
13. Click Done.
14. Click Create.\
![GCP Classic VPN gateway and tunnel configuration form completed]()
\\
![GCP Classic VPN tunnel creation confirmation screen]()
## HA VPN Configuration
Creating an HA VPN on GCP is a three-step process as follows:
**Create Cloud HA VPN Gateway**
1. In the Cloud HA VPN gateway section, provide a Name.
2. For Network, select the GCP network that needs to be able to access MacStadium.
3. Select Region.
4. Click CREATE & CONTINUE Add VPN tunnels.
5. In the VPN Tunnels section, make sure On-prem or Non Google Cloud is selected and click Peer VPN gateway name > CREATE NEW PEER VPN GATEWAY.
6. Provide a Name for the VPN Gateway and confirm that two interfaces is selected at the next section.
7. For both Interface 0 IP address and Interface 1 IP address fields, provide the IP address of the public network listed in Appendix B of the IP Plan. By default, this is the FW1-Outside network. Click CREATE.
8. In the Routing options section, click Cloud Router > Create new router.
9. Provide a Name and Description.
10. In Google ASN, provide any private ASN number (64512 - 65534, 4200000000 - 4294967294).
11. Keep the other options with the default values and click CREATE.
12. In the VPN tunnels section you need to configure both VPN tunnels.
13. Select the first VPN tunnel.
14. Provide a Name, Description and confirm IKEv2 is selected.
15. Provide or generate an IKE pre-shared key and click DONE.
Keep a record of the pre-shared key. It is needed later.
16. Select the second VPN tunnel and repeat the steps 10 and 11.
17. Click CREATE & CONTINUE. Wait a few seconds while the VPN tunnels are created.
## Configure BGP Sessions
Scroll right and click CONFIGURE BGP SESSION at the first VPN tunnel.
1. Provide a Name and the Peer ASN. This is also the ASN you will use to configure BGP on your MacStadium Firewall. You can choose any private ASN (64512 - 65534, 4200000000 - 4294967294) but it must be different from the ASN assigned to the Cloud Router configured on the previous step.
2. Keep the default values for all other options and click SAVE AND CONTINUE.
3. Scroll right and click CONFIGURE BGP SESSION at the second VPN tunnel.
4. Repeat steps 2 and 3 to configure the BGP settings of the second VPN tunnel. Notice that the same Peer ASN should be used.
5. Click SAVE BGP CONFIGURATION.
6. In the Summary and reminder page, click DOWNLOAD CONFIGURATION.
7. For Vendor select Cisco. For Platform, at the time of writing, Firepower is the only option available. On Software, confirm that >= ASA 9.13(1)2 is selected and click DOWNLOAD.
8. Next click OK.
After the creation is complete, the VPN tunnel status is: No incoming packets.
The following image shows a sample configuration for the HA VPN gateway and tunnel.
![GCP HA VPN gateway configuration form with name and network fields]()
![GCP peer VPN gateway configuration with two interface IP fields]()
![GCP Cloud Router configuration form with name and ASN fields]()
![GCP HA VPN tunnel configuration form with name and IKE pre-shared key fields]()
![GCP VPN tunnel summary page before creation]()
![GCP BGP session configuration form with peer ASN field]()
![GCP Download Configuration dialog with Cisco vendor options]()
![GCP HA VPN gateway created with two tunnel interfaces showing status]()
![GCP HA VPN tunnel detail showing overall status]()
## Ensure that GCP Firewall Allows Ingress Traffic
Based on the requirements, it might be necessary to enable ingress traffic from MacStadium to GCP in the GCP firewall. For more information, see Google Cloud Documentation: [Configure Firewall Rules](https://cloud.google.com/network-connectivity/docs/vpn/how-to/configuring-firewall-rules#example_configurations).
## Preparing the VPN Configuration
To prepare the VPN configuration, see [GCP VPN Config for Cisco ASA/ASAv](/iaas/google-cloud-platform/gcp-vpn-config-for-cisco-asaasav).
## GCP VPN Config for Cisco ASA/ASAv
After the Site-to-Site VPN connection is created in Google Cloud Platform (GCP), configure the Cisco firewall to recognize the connection and let traffic into the MacStadium private cloud.
Use the configuration template provided below and fill in the missing information. Data from both GCP and MacStadium is required.
1. Configuration template.
2. Fill in the configuration blanks.
3. Get the configuration values.
4. Complete the template.
## Configuration Template Classic VPN
Do not attempt GCP and ASA/ASAv configuration without proper experience, or unexpected consequences may happen to the VPN.
This is a template configuration that can be used to complete the setup of the GCP-MacStadium Site-To-Site Classic VPN connection.
`! #1: Placeholders !
! \{ gcp_network_address } - The address of the GCP local network that needs to have access to MacStadium.
! \{ gcp_network_mask } - The subnet mask of the GCP local network that needs to have access to MacStadium. ! \{ gcp_vpn_ip } - The public IP address of the cloud VPN gateway in GCP. ! \{ macstadium_public_ip } - The IP address of the public network of your MacStadium private cloud. By default, this is FW1-Outside. ] ! \{ macstadium_network_name } - The name of the private network in MacStadium that needs ]to be accessed by GCP. By default, this is Private-1. ! \{ macstadium_network_address } - The IP address of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1. ! \{ macstadium_network_mask } - The subnet mask of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1. ! \{ macstadium_outside_interface } - The name of the outside interface of your Cisco ASA/ASAv device. By default, this is Outside. ! \{ shared_key } - The IPSec pre-shared key used when creating the VPN connection in GCP.
! ! #2: NAT exemption ! ! The name "GCP-NET" must be unique for the Cisco ASA/ASAv device. ! object-group network GCP-NET description GCP Virtual Network network-object \{ gcp_network_address } \{ gcp_network_mask } ! The name "ONPREM-NET" must be unique for the Cisco ASA/ASAv device. object-group network ONPREM-NET description OnPrem Network network-object \{ macstadium_network_address } \{ macstadium_network_mask } ! The names "gcp-in", "gcp-acl", and "gcp-filter" must be unique for the Cisco ASA/ASAv device. access-list gcp-in extended permit ip host \{ gcp_vpn_ip } host \{ macstadium_public_ip } access-list gcp-acl extended permit ip any4 object-group GCP-NET access-list gcp-filter extended permit ip object-group GCP-NET object-group ONPREM-NET nat (\{ macstadium_network_name },\{ macstadium_outside_interface }) 1 source static ONPREM-NET ONPREM-NET destination static GCP-NET GCP-NET ! #3: IKE & IPSec configuration
! ! The name "gcp" must be unique for the Cisco ASA/ASAv device. crypto ipsec ikev2 ipsec-proposal gcp protocol esp encryption aes-256 protocol esp integrity sha-1 ! The name "gcp-vpn-map" must be unique for the Cisco ASA/ASAv device. crypto map gcp-vpn-map 1 match address gcp-acl crypto map gcp-vpn-map 1 set pfs group14 crypto map gcp-vpn-map 1 set peer \{ gcp_vpn_ip } crypto map gcp-vpn-map 1 set ikev2 ipsec-proposal gcp crypto map gcp-vpn-map interface \{ macstadium_outside_interface } crypto ikev2 policy 100 encryption aes-256 integrity sha512 group 14 prf sha lifetime seconds 36000
exit crypto ikev2 enable \{ macstadium_outside_interface } crypto ipsec security-association lifetime seconds 10800 crypto ipsec security-association replay window-size 128 crypto ipsec security-association pmtu-aging infinite crypto isakmp identity address crypto isakmp disconnect-notify no crypto isakmp nat-traversal crypto ipsec df-bit clear-df Outside group-policy gcp internal group-policy gcp attributes vpn-filter value gcp-filter vpn-tunnel-protocol ikev2 tunnel-group \{ gcp_vpn_ip } type ipsec-l2l tunnel-group \{ gcp_vpn_ip } general-attributes default-group-policy gcp tunnel-group \{ gcp_vpn_ip } ipsec-attributes isakmp keepalive threshold 10 retry 3 ikev2 remote-authentication pre-shared-key \{ shared_key } ikev2 local-authentication pre-shared-key \{ shared_key }`
## Configuration Template HA VPN
Do not attempt GCP and ASA/ASAv configuration without proper experience, or unexpected consequences may happen to the VPN.
This is a template configuration that you can use to complete the setup of your GCP-MacStadium Site-To-Site HA VPN connection.
`! #1: Placeholders ! ! \{ gcp_network_address } - The address of the GCP local network that needs to have access to MacStadium. ! \{ gcp_network_mask } - The subnet mask of the GCP local network that needs to have access to MacStadium. ! \{ gcp_network_mask_cidr } - The subnet mask of the GCP local network that needs to have access to MacStadium in CIDR notation. Ex: 255.255.255.0 in CIDR notation is /24. ! \{ gcp_vpn_ip0 } - The public IP address of the first VPN Gateway interface in GCP. ! \{ gcp_vpn_ip1 } - The public IP address of the second VPN Gateway interface in GCP. ! \{ macstadium_public_ip } - The IP address of the public network of your MacStadium private cloud. By default, this is FW1-Outside. ! \{ macstadium_network_name } - The name of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1.
! \{ macstadium_network_address } - The IP address of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1. ! \{ macstadium_network_mask } - The subnet mask of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1. ! \{ macstadium _network_mask_cidr } - The subnet mask in CIDR notation of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1. Ex: 255.255.254.0 in CIDR notation is /23 ! \{ macstadium_outside_interface } - The name of the outside interface of your Cisco ASA/ASAv device. By default, this is Outside. ! \{ shared_key0 } - The IPSec pre-shared key used when creating the first VPN connection in GCP. ! \{ shared_key1 } - The IPSec pre-shared key used when creating the second VPN connection in GCP. ! \{ gcp_bgp_ip_address0 } - The Cloud router BGP IP address of the first BGP session in GCP. ! \{ gcp_bgp_ip_address1 } - The Cloud router BGP IP address of the second BGP session in GCP. ! \{ macstadium_bgp_ip_address0 } - The BGP peer IP address of the first BGP session in GCP. ! \{ macstadium_bgp_ip_address1 } – The BGP peer IP address of the second BGP session in GCP. ! \{ macstadium_bgp_asn } – The BGP peer router ASN of the BGP sessions configuration in GCP. ! \{ gcp_bgp_asn } – The BGP router ASN on the Cloud Router configuration in GCP. ! ! #1: IKE & IPSec configuration ! ! The name "gcp" must be unique for the Cisco ASA/ASAv device. ! configure terminal crypto ipsec ikev2 ipsec-proposal gcp protocol esp encryption aes-gcm-256 protocol esp integrity sha-512 !
crypto ipsec profile gcp set ikev2 ipsec-proposal gcp set pfs group14 set security-association lifetime kilobytes unlimited set security-association lifetime seconds 10800 ! crypto ipsec security-association pmtu-aging infinite ! crypto ikev2 policy 10 encryption aes-gcm-256 integrity null group 14 prf sha512 sha384 sha256 sha lifetime seconds 36000 crypto ikev2 policy 100 encryption aes-256 integrity sha512 group 14 prf sha lifetime seconds 36000 ! crypto ikev2 enable \{ macstadium_outside_interface } !
group-policy gcp internal group-policy gcp attributes vpn-tunnel-protocol ikev2 ! tunnel-group \{ gcp_vpn_ip0 } type ipsec-l2l tunnel-group \{ gcp_vpn_ip0 } general-attributes default-group-policy gcp tunnel-group \{ gcp_vpn_ip0 } ipsec-attributes isakmp keepalive threshold 10 retry 3 ikev2 remote-authentication pre-shared-key \{ shared_key0 } ikev2 local-authentication pre-shared-key \{ shared_key0 } ! tunnel-group \{ gcp_vpn_ip1 } type ipsec-l2l tunnel-group \{ gcp_vpn_ip1 } general-attributes default-group-policy gcp tunnel-group \{ gcp_vpn_ip1 } ipsec-attributes isakmp keepalive threshold 10 retry 3 ikev2 remote-authentication pre-shared-key \{ shared_key1 } ikev2 local-authentication pre-shared-key \{ shared_key1 } ! ! #2: Tunnel interfaces configuration ! ! The name Tunnel interface number, "gcp-if-0" and "gcp-if-1" must be unique for the Cisco ASA/ASAv device. interface Tunnel0 nameif gcp-if-0 ip address \{ macstadium_bgp_ip_address0 } 255.255.255.252 tunnel source interface \{ macstadium_outside_interface } tunnel destination \{ gcp_vpn_ip0 } tunnel mode ipsec ipv4 tunnel protection ipsec profile gcp
! interface Tunnel1 nameif gcp-if-1 ip address \{ macstadium_bgp_ip_address1 } 255.255.255.252 tunnel source interface \{ macstadium_outside_interface } tunnel destination \{ gcp_vpn_ip1 } tunnel mode ipsec ipv4 tunnel protection ipsec profile gcp ! ! #3: Access control configuration ! ! The name “gcp-vpc-lan”, “gcp-in” and “gcp-out” must be unique for the Cisco ASA/ASAv device. object network gcp-vpc-lan subnet \{ gcp_network_address } \{ gcp_network_mask } ! access-list gcp-in extended permit ip any any ! access-group gcp-in in interface gcp-if-0 control-plane access-group gcp-in in interface gcp-if-0 access-group gcp-in in interface gcp-if-1 control-plane access-group gcp-in in interface gcp-if-1
! prefix-list gcp-in seq 5 permit \{ gcp_network_address }/\{ gcp _network_mask_cidr } le 32 ! prefix-list gcp-out seq 5 permit \{ macstadium_network_address }/\{ macstadium _network_mask_cidr } le 32 ! router bgp \{ macstadium_bgp_asn } bgp log-neighbor-changes bgp graceful-restart address-family ipv4 unicast neighbor \{ gcp_bgp_ip_address0 } remote-as \{ gcp_bgp_asn } neighbor \{ gcp_bgp_ip_address0 } ebgp-multihop 2 neighbor \{ gcp_bgp_ip_address0 } activate neighbor \{ gcp_bgp_ip_address0 } prefix-list gcp-in in neighbor \{ gcp_bgp_ip_address0 } prefix-list gcp-out out neighbor \{ gcp_bgp_ip_address0 } maximum-prefix 100 70 neighbor \{ gcp_bgp_ip_address1 } remote-as \{ gcp_bgp_asn } neighbor \{ gcp_bgp_ip_address1 } ebgp-multihop 2 neighbor \{ gcp_bgp_ip_address1 } activate neighbor \{ gcp_bgp_ip_address1 } prefix-list gcp-in in neighbor \{ gcp_bgp_ip_address1 } prefix-list gcp-out out neighbor \{ gcp_bgp_ip_address1 } maximum-prefix 100 70 network \{ macstadium_network_address } mask \{ macstadium_network_mask } maximum-paths 2 no auto-summary no synchronization exit-address-family end write memory`
## Fill in the Configuration Blanks
Manually replace the placeholders in the configuration template with the values for your GCP and MacStadium configurations.
### Get the Configuration Values
1. Confirm login to the GCP console.\\
![GCP console project selector in the toolbar]()
2. In the GCP search bar, type VPN and select VPN Hybrid Connectivity.\\
![GCP search bar with VPN typed and VPN Hybrid Connectivity result]()
* `{ gcp_network_address }`, `{ gcp_network_mask_cidr }` and `{ gcp_network_mask_cidr }`
* This is the IP address of the GCP local network that needs to have access to MacStadium.
3. Select Cloud VPN Gateways.
4. Locate the gateway used by the GCP-MacStadium tunnel and note the value for Region.\\
![GCP Cloud VPN Gateways list showing gateway region and VPC network link]()
5. Click the value listed under VPC network.
* The GCP console redirects you to the list of subnets for the selected network.
6. In the list of subnets, locate the one matching the region selected earlier.
7. Obtain the values from the Internal IP ranges field. Example:
* `Region: us-east1 Internal IP range: 10.142.0.0/20 { gcp_network_address }: 10.142.0.0 { gcp_network_mask }: 255.255.240.0 { gcp_network_mask_cidr }: /20`
* This is the public IP addresses of the Cloud VPN gateway interfaces in GCP.
8. In the VPN Hybrid Connectivity service page, select Cloud VPN Gateways.
9. Locate the gateway used by the GCP-MacStadium tunnel and use the values listed under IP address.\\
![GCP Cloud VPN Gateways list showing gateway IP address fields]()
* `{ macstadium_public_ip }`
* This is the IP address of the public network of the MacStadium private cloud. By default, this is FW1-Outside. Information about the public network is located in Appendix B of the IP Plan.\
`{ macstadium_network_name }`
* This is the name of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1. Information about the public network is located in Appendix B of the [IP Plan](/macstadium/macstadium-overview/ip-plan).
* `{ macstadium_network_address }`
* This is the Subnet ID of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1 Subnet ID. Information about the public network is located in Appendix B of the IP Plan
* `{ macstadium_network_mask }`
* This is the subnet mask of the private network in MacStadium that needs to be accessed by GCP. By default, this is Private-1 Subnet. Information about the public network is located in Appendix B of the IP Plan.
* `{ macstadium _network_mask_cidr }`
* To convert the subnet mask to a CIDR notation, use a CIDR calculator such as this CIDR/Netmask Lookup Tool.
* `{ macstadium_outside_interface }`
* This is the name of the private network in MacStadium that needs to be accessed by GCP. By default, this is Outside. Information about the public network is located in Appendix B of the IP Plan.
* `{ shared_key0 }` and `{ shared_key1 }`
* This is the IPSec pre-shared key used when creating the VPN connection in GCP.
* This key must be saved separately. Obtain it from the VPN configuration downloaded from GCP.
* `{ gcp_bgp_ip_address0 }` and `{ gcp_bgp_ip_address1 }`
* The Cloud router BGP IP address of the BGP sessions in GCP.
* In the VPN Hybrid Connectivity service page, select Cloud VPN Tunnels.
10. In the VPN Hybrid Connectivity service page, select Cloud VPN Tunnels.
11. Locate the VPN tunnels used by your GCP-MacStadium VPN and use the values listed under Cloud Router BGP IP address.\\
![GCP Cloud VPN Tunnels list showing Cloud Router BGP IP address column]()
```
* ` { macstadium_bgp_ip_address0 } and { macstadium_bgp_ip_address1 }`
```
12. In the VPN Hybrid Connectivity service page, select Cloud VPN Tunnels.
13. Locate the VPN tunnels used by your GCP-MacStadium VPN and use the values listed under Peer BGP IP address.\\
![GCP Cloud VPN Tunnels list showing Peer BGP IP address column]()
```
* `{ gcp_bgp_asn }`
```
14. In the VPN Hybrid Connectivity service page, select Cloud VPN Tunnels.
15. Locate the VPN tunnels used by your GCP-MacStadium VPN, click the Actions button and select View.\\
![GCP Cloud VPN Tunnels list with Actions button and View option]()
16. Use the value of the Cloud Router ASN field. Both tunnels should have the same value for this parameter.\\
![GCP VPN tunnel detail showing Cloud Router ASN field]()
```
* `{ macstadium_bgp_asn }`
```
17. In the VPN Hybrid Connectivity service page, select Cloud VPN Tunnels.
18. Locate the VPN tunnels used by the GCP-MacStadium VPN, and click Actions.
19. Select View.\\
![GCP Cloud VPN Tunnels list with Actions button and View option]()
20. Use the value of the Cloud Router ASN field. Both tunnels should have the same value for this parameter.\\
![GCP VPN tunnel detail showing Cloud Router ASN field]()
## Complete the Template
1. Copy the template into a text editing tool.
2. Replace all placeholders with their respective values.
3. Delete the remaining commented lines to clean up the template. Commented lines are indicated by ! at the beginning of the line.
4. Apply the config to your firewall and save your changes.
## TCP State Bypass
After the VPN is configured, configure TCP State Bypass on the ASA / ASAv firewall in order to allow the outbound and inbound traffic to flow through separate VPN tunnels.
| Placeholder | Description | More Information | Example |
| -------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------- |
| `{acl-state-bypass}` | A unique name for the access control list that permits the creation of the tunnel and the traffic over it. | Cisco Documentation: Access Control Lists | acl-state-bypass |
| `{cm_state-bypass}` | A unique name for the Class-map. | Cisco Documentation: TCP State Bypass | cm-state-bypass |
| `{pm-state-bypass}` | A unique name for the access control list that permits the creation of the tunnel and the traffic over it. | Cisco Documentation: TCP State Bypass | pm-state-bypass |
1. Define the Access list with the source and destination networks:
* `access-list { acl-state-bypass } extended permit ip { macstadium_network_address } { macstadium_network_mask } { gcp_network_address } { gcp_network_mask }`
2. Create the Class Map to identify the traffic to disable stateful Firewall inspection:
* `class-map { cm-state-bypass }`
3. Enter the match parameter command to specify the traffic of interest within the class map.
* `match access-list { acl-state-bypass }`
4. Enter the policy-map name command to assign the actions to be taken in regards to the specified class map traffic:
* `policy-map { pm-state-bypass } class { cm-state-bypass } set connection advanced-options tcp-state-bypass`
5. Enter the service-policy command in global configuration mode in order to activate the policy map on the targeted interface:
* `service-policy { pm-state-bypass } interface { macstadium_network_name }`
6. Save changes:
* `write memory`
* To feed the complete configuration into your Cisco ASA/ASAv, see [Site-to-Site VPN Config](/iaas/connecting-to-other-clouds/site-to-site-vpn-config).
# Verify your GCP-to-MacStadium VPN connection
Source: https://docs.macstadium.com/iaas/google-cloud-platform/verify-gcp
Verify a GCP-MacStadium VPN using the Cisco ASDM-IDM CLI. Checks ISAKMP security associations to confirm the tunnel is active after configuration.
After you have completed both the Google Cloud Platform (GCP) and the MacStadium sides of the configuration, you might want to verify that the tunnel is working as expected.
1. Verify that you are connected via VPN to your MacStadium private cloud.
* For more information about how to connect to the VPN, see [Connecting to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
* For more information about how to log in to your firewall, see [Logging into Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
3. In the Cisco ASDM-IDM application toolbar, select **Tools > Command Line Interface**.\\
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line, enter the following command, and click **Send**.
```
show crypto isakmp sa
```
If the site-to-site VPN connection is configured properly, you should see information about an active IKEv1.
For more information about this verification command, see [Cisco Documentation: show crypto isakmp sa](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#isakmp_sa).
## Verify that there is an IPsec security association between peers
1. Verify that you are connected via VPN to your MacStadium private cloud.
* For more information about how to connect to the VPN, see [Connecting to Your Cloud via VPN](/remote-desktop-vdi/cloud-access-legacy/connect-to-your-cloud-via-vpn).
2. Run Cisco ASDM-IDM and log in.
* For more information about how to log in to your firewall, see [Logging into Cisco Firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall).
3. In the Cisco ASDM-IDM application toolbar, select Tools > Command Line Interface\\
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select Single Line, enter the following command, and click Send.
```
show crypto ipsec sa
```
If the site-to-site VPN connection is configured properly, you should see a detailed log.
For more information about this verification command, see [Cisco Documentation: show crypto ipsec sa](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#ipsec_sa).
## Verify that the tunnel is connected
1. Log in to your GCP console.
2. From the GCP console sidebar, scroll to the Networking section and select **Hybrid Connectivity > VPN**.\\
![GCP Hybrid Connectivity VPN navigation in sidebar]()
3. On the Cloud VPN Tunnels tab, locate the tunnel to MacStadium and check the value for VPN tunnel status. When your tunnel is properly connected, the status is: Established.\\
![GCP Cloud VPN Tunnels tab showing tunnel status as Established]()
## Test traffic and visibility through the tunnel
1. Verify that you have created a virtual machine in MacStadium.
2. Verify that you have created a virtual machine instance in GCP and that you have enabled user login on it.
* For more information about user login on GCP instances, see [Google Cloud Documentation: Setting up and configuring OS Login](https://cloud.google.com/compute/docs/instances/managing-instance-access).
3. In the terminal on your MacStadium VM, run the following command.
* Replace `` with the username for your GCP instance.
* Replace `` with the private IP of the GCP instance.
```
ssh @
```
4. When prompted, provide your password or key for the specified username on the specified GCP instance.
* If the connection is successful, the prefix of the terminal becomes ``@``. This indicates that you have connected from MacStadium to GCP over the tunnel.
5. Run the following command.
* Replace `` with the username for your MacStadium VM.
* Replace `` with the private IP of the MacStadium VM.
```
ssh @
```
6. When prompted, provide your password or key for the specified username on the specified MacStadium VM.
* If the connection is successful, the prefix of the terminal becomes ``@``. This indicates that you have connected from GCP to MacStadium over the tunnel.
## Troubleshooting
See our [GCP Troubleshooting](/iaas/google-cloud-platform/gcp-troubleshooting) doc for some common issues with GCP-MacStadium Site-to-Site VPN Connections.
# Can I change the OS on my server from macOS to Linux?
Source: https://docs.macstadium.com/iaas/iaas-faqs/can-i-change-the-os-on-my-server-from-macos-to-linux
Mac servers at MacStadium run macOS and cannot be converted to Linux. For Linux or Windows workloads, MacStadium recommends Private Cloud x86 VMs instead.
MacStadium recommends our Private Cloud x86 VMs for Linux or Windows OS.
# Root and admin access on MacStadium Mac servers
Source: https://docs.macstadium.com/iaas/iaas-faqs/do-i-have-root-and-admin-access-to-subscription-based-mac-servers
MacStadium provides admin access on every macOS subscription with SSH and VNC enabled by default. Full system control, subject to the Terms of Service.
For every subscription to a hosted Mac running macOS, we provide an administrator account and the ability to modify system-level files. Login as administrator to a Mac running macOS and you have complete control over the system.
SSH and VNC access are enabled by default on dedicated servers so you can access them from any device. It's no different than if the server were on your local network.
We do require that you follow the guidelines set in our [Terms of Service and Acceptable Use Policy](https://www.macstadium.com/legal) which you must agree to during checkout.
# MacStadium REST API for server management
Source: https://docs.macstadium.com/iaas/iaas-faqs/macstadium-api
Automate MacStadium server management via REST API at api.macstadium.com. Use HTTP Basic or Bearer token auth to list servers, reboot, and query status.
Interact with our system programmatically from your own applications
## How It Works
The API is similar to the [RESTful](https://en.wikipedia.org/wiki/Representational_State_Transfer) architecture, accepting and returning JSON data. Authentication is implemented as HTTP Basic Authentication over SSL (`https`) and Bearer token (generated from Users page, Tokens tab). Failed authentication attempts return a `401 Unauthorized`. 20 failed authentication attempts lock out the requesting IP for 5 minutes (no response).
The examples below include the [HTML contenteditable attribute](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content) to allow adjustment of credentials and/or IP address prior to copying and pasting elsewhere, e.g., your terminal.
### List All Servers
URI: `https://api.macstadium.com/core/api/servers`\
Request: `GET`\
Return: JSON array of `{id, name, ip, type, location, status, creation_date, cancel_date}` or error string. Servers with multiple IPs will have multiple listings.
**Example 1:**
```bash theme={null}
curl -H "Accept: application/json" -H "Content-Type: application/json" -X GET -u user:pass https://api.macstadium.com/core/api/servers
```
**Example 2:**
```bash theme={null}
curl -H "Accept: application/json" -H "Content-Type: application/json" -H 'Authorization: Bearer {token}' -X GET https://api.macstadium.com/core/api/servers
```
### Server Status by ID/IP
URI: `https://api.macstadium.com/core/api/servers/{id or ip_address}`\
Request: `GET`\
Return: JSON array of `{id, name, power, type, location, status, creation_date, cancel_date}` or error string. `power` can be `On`, `Off`, `Rebooting`, or `Error`.
**Example 1:**
```bash theme={null}
curl -H "Accept: application/json" -H "Content-Type: application/json" -X GET -u user:pass https://api.macstadium.com/core/api/servers/192.168.1.101
```
**Example 2:**
```bash theme={null}
curl -H "Accept: application/json" -H "Content-Type: application/json" -X GET -H 'Authorization: Bearer {token}' https://api.macstadium.com/core/api/servers/192.168.1.101
```
### Server Action (Power) by ID/IP
URI: `https://api.macstadium.com/core/api/servers/{id or ip_address}/{action}`\
Request: `GET`\
Params: `action` can be `On`, `Off`, or `Reboot` (case insensitive).\
Return: String. `True` on success or an error message.
**Example 1:**
```bash theme={null}
curl -H "Accept: application/json" -H "Content-Type: application/json" -X GET -u user:pass https://api.macstadium.com/core/api/servers/192.168.1.101/reboot
```
**Example 2:**
```bash theme={null}
curl -H "Accept: application/json" -H "Content-Type: application/json" -X GET -H 'Authorization: Bearer {token}' https://api.macstadium.com/core/api/servers/192.168.1.101/reboot
```
# Hard reboot a MacStadium Mac from the portal
Source: https://docs.macstadium.com/iaas/iaas-faqs/reboot-your-mac
Mac not responding and SSH is down? Use Hard Reboot in the MacStadium portal. Includes Energy Saver settings so the Mac comes back online automatically.
If your Mac locks up or connecting via SSH becomes unavailable, you should first use the Power Management ‘Hard Reboot’ feature included with every dedicated MacStadium server subscription via your control panel on the MacStadium website. Click a subscription, then select 'Hard Reboot' on the right hand side of the page.
![PortalReboot.png]()
By clicking this button, you are sending a signal to a power-supply dedicated to your Mac in the data center. The power-supply will drop power for a few seconds and then restore power.
In order for this feature to work as desired, it is important that your Mac's Energy Saver/Battery settings are configured as shown below. All of our macs are configured with these settings by default, so no adjustment is needed.
In macOS Ventura (13.x), Sonoma (14.x), Sequoia (15.x) and later, select **System Settings** from the **Apple Menu** and configure as follows:
* Under the **Energy Saver** section:
* Enable Prevent automatic sleeping when the display is off
* Enable Start up automatically after a power failure
* Enable Wake for network access
* Under the **Lock Screen** section:
* Set Turn display off when inactive to Never
* Under the **Displays** section:
* Set **Advanced** > **Prevent automatic sleeping on power adapter when the display is off** (if available)
In earlier versions of macOS (Monterey (12.x) and older), select System Preferences from the Apple Menu and configure as follows:
* Click **Energy Saver**
* Set **Display Sleep** to **Never**
* Computer Sleep: Set to Never
* Uncheck ‘Put the hard disks to sleep when possible’
* Check ‘Wake for Ethernet network administrator access’
* Uncheck ‘Allow power button to sleep the computer’
* Check ‘Restart automatically after a power failure’
* Click Schedule
* Set Start up or wake Every day at 4AM (in case you ever accidentally shut your mac down permanently)
# Troubleshooting Connectivity Issues
Source: https://docs.macstadium.com/iaas/iaas-faqs/troubleshooting-connectivity-issues
Can't connect to your MacStadium device? Self-service guide: run a traceroute to find where the connection breaks, then check VPN and firewall settings.
If you're unable to connect to your device, follow these self-remediation steps in order to diagnose and resolve the issue.
## Step 1: Verify Network Path with Traceroute
Run a traceroute to your device to check accessibility and identify where the connection path breaks:
**For macOS and Linux users:**
```
traceroute
```
**For Windows users:**
```
tracert
```
Analyze the traceroute results to determine the issue:
### Issue: Route fails to reach MacStadium data center
**Likely cause:** Local network, firewall, or VPN configuration blocking access.
**Resolution:**
1. Verify your local internet connection is working properly
2. Check your firewall settings to ensure traffic to MacStadium data centers is allowed
3. If you're using a VPN:
* Confirm the VPN connection is active
* Verify your VPN configuration permits access to MacStadium IP ranges
4. Try connecting from a different network to rule out local network restrictions
### Issue: Route reaches MacStadium data center but stops before the device
**Likely cause:** Your device may be powered off.
**Resolution:**
1. Power on the device through the portal
2. Wait 2-3 minutes for the machine to fully boot
3. Test connectivity with another traceroute /tracert or ping:
```
ping
```
4. Once the device responds to ping, attempt your VNC connection again
### Issue: Route reaches your device, but VNC connection fails
**Likely cause:** VNC service issue or incorrect port configuration.
**Resolution:**
1. Verify you're using the correct VNC port for your device
2. Restart the device through the portal
3. Wait 2-3 minutes for the machine to fully boot
4. Test connectivity with another traceroute /tracert or ping:
## Step 2: Still having issues?
If you've completed all the steps above and still cannot connect to your device, please open a support ticket with the following information:
* The issue you're experiencing
* Results from your traceroute
* Steps you've already attempted
* Any error messages you're receiving
Our support team will investigate further and help resolve your connectivity issue.
# Data Center Locations
Source: https://docs.macstadium.com/iaas/iaas-overview/data-center-locations
MacStadium data centers in Atlanta, Las Vegas, and Dublin. Test IP addresses are provided to measure latency from your location before choosing a region.
When choosing a data center to start a subscription, keep in mind the geographic locations of all those attempting to access the server. If low latency is important, then the closer the servers are physically, the better the connection quality is.
Here is a set of IP addresses, one for each data center, to test latency or perform a trace route:
### Atlanta
208.52.190.1
### Dublin
208.83.1.1
### Las Vegas
207.254.73.1
# Infrastructure as a Service (IaaS)
Source: https://docs.macstadium.com/iaas/iaas-overview/infrastructure-as-a-service-iaas
MacStadium IaaS: bare metal Mac access across data centers in Las Vegas, Atlanta, and Dublin. SOC 1/2/3 and ISO 27001/27017/27018 certified infrastructure.
## About
Infrastructure as a Service (IaaS) at MacStadium provides secure, high-performance access to bare metal Mac infrastructure, optimized for a variety of development, testing, and general compute workflows.
## Overview
MacStadium has three secure global data centers across the globe:
* **Las Vegas, USA**
* **Atlanta, USA**
* **Dublin, Ireland**
The data centers adhere to industry-leading security and compliance certifications, including SOC 1, SOC 2, SOC 3, ISO 27001, 27017, and 27018.
For more details, visit the [Trust page](https://trust.macstadium.com/).
## Getting Started
### Bare metal Mac models
MacStadium offers a variety of standard models of the latest Mac Mini and Mac Studio configurations, optimized for various tasks.
These models provide flexibility for users requiring different levels of performance, from lightweight testing to resource-heavy production environments.
### Networking and Storage
MacStadium infrastructure provides networking and storage solutions that address secure access and throughput controls.
* **Cisco ASAv Firewalls**: High-end and high-performance firewall systems that ensure secure network segmentation and traffic management.
* **Pure Storage**: Reliable, high-speed storage for optimal data performance and redundancy.
* **MacStadium Private Cloud Networking**: Networking solution to provide for secure access and up to 1 Gbps throughput.
### Key differentiators
* **Optimized Mac Models**: Mac Mini and Mac Studio offerings are designed to handle a wide range of tasks, from development and testing to high-performance media production environments.
* **Consistent Pricing**: Enjoy predictable fixed pricing, ensuring cost efficiency to scale.
* **Integrated Virtualization with Orka**: MacStadium provides the best experience in managed Orka deployments for virtualized Mac compute at scale.
* **Apple Expertise**: With years of specialized experience in Mac infrastructure, MacStadium delivers a high-level of service and support.
* **High Security Standards**: MacStadium complies with enterprise security standards, ensuring customer data and operations remain safe and compliant.
## Data center certifications
All of our data centers are audited and/or certified by various internationally-recognized attestation and certification compliance standards. For a full list of certifications, please visit the [Trust Center](https://trust.macstadium.com/).
# MacStadium IaaS networking overview
Source: https://docs.macstadium.com/iaas/networking/networking-overview
Overview of MacStadium IaaS networking: VPN access, site-to-site tunnels to AWS, Azure, and GCP, custom domains, firewall config, and IP Plan resources.
MacStadium IaaS environments run on a private network. All access, whether you're connecting from your local machine, a cloud provider, or a CI/CD system, goes through one of the networking options below.
## VPN access
The most common way to connect to your MacStadium environment. MacStadium provisions a Cisco ASA or ASAv firewall with VPN access included. You connect using a VPN client (Cisco AnyConnect or compatible) with credentials provided at onboarding.
* [Firewall overview and hardware options](/iaas/cisco-firewalls/network-firewalls-overview)
* [Network onboarding form](/iaas/cisco-firewalls/network-onboarding-form)
* [Prepare VPN config for Cisco ASA/ASAv](/iaas/cisco-firewalls/prepare-the-vpn-configuration-for-input-into-cisco-asaasav)
## Site-to-site VPN tunnels
For persistent, automated connectivity between your MacStadium environment and a public cloud, use a site-to-site IPsec VPN tunnel. MacStadium supports tunnels to AWS, Azure, and Google Cloud Platform.
* [Connect to AWS](/iaas/aws/site-to-site-vpn-configuration-with-aws)
* [Connect to Azure](/iaas/azure/site-to-site-vpn-configuration-with-azure)
* [Connect to GCP](/iaas/google-cloud-platform/site-to-site-vpn-configuration-with-gcp)
* [Connect to other clouds](/iaas/connecting-to-other-clouds/other-clouds)
## IP plan
Every MacStadium environment is assigned a private IP range. Your IP plan document (provided at onboarding) maps out your assigned addresses, gateway IPs, and subnet structure. Keep this on hand; you'll reference it when configuring VPN tunnels and firewall rules.
* [Understanding your IP plan](/macstadium/macstadium-overview/ip-plan)
## Firewall configuration
MacStadium-provisioned Cisco firewalls are fully customer-configurable. You have root access to manage rules, users, and VPN settings directly.
* [Log in to your firewall](/iaas/cisco-firewalls/logging-into-cisco-firewall)
* [Configure the firewall](/iaas/cisco-firewalls/network-firewalls-configuration)
* [Allow specific IPs from the internet](/iaas/cisco-firewalls/allowing-specific-ips-to-access-macstadium-via-internet)
* [Submit a firewall change request](/iaas/cisco-firewalls/firewall-change-request-form)
# Private Cloud Network Attached Storage
Source: https://docs.macstadium.com/iaas/storage/private-cloud-network-attached-storage
Create and manage a NAS virtual machine in MacStadium Private Cloud to share storage across VMs and machines on your private network.
Network Attached Storage (NAS) devices are specialized servers that handle only data storage and file-sharing requests. They provide fast, secure, and reliable storage services to private networks.
NAS is managed through the same interface as other virtual servers in the network, so it can move from one physical host to another. NAS functionality can be added by downloading and implementing an instance of the standard NAS VM Recipe.
The NAS service is a dedicated virtual machine that presents itself as a service providing users the ability to create and manage file based storage without the need for using physical or virtual appliances. Each NAS service is complete with its own dashboard and is completely managed from the user interface.
## About NAS
NAS lets you take storage in Private Cloud and expose it to other machines, then share that storage between machines. It is a virtual NAS with redundancy. NAS storage can be exposed to other machines over the network.
NAS allows for virtual machines to share storage with assets inside or outside of the Private Cloud, then use a file share to move files back and forth between machines.
NAS is used to expand storage and to share files between Macs, and you can configure this yourself.
## Create the NAS Service
The NAS service is a dedicated virtual machine that presents itself as a service providing users the ability to create and manage file based storage without the need for using physical or virtual appliances. Each NAS service includes its own dashboard and is fully managed from the user interface. Using the integrated NAS service takes advantage of the VergeIO snapshot engine and deduplication algorithm to get the most of usable storage space.
1. From the Cloud Dashboard, select **NAS** from the left menu.
![Private Cloud left sidebar with NAS option highlighted]()
NAS
2. The **NAS Dashboard** opens.
For a new user, when this dashboard is opened for the first time, there are no NAS services or volumes. A NAS Service is the virtual machine in Private Cloud that runs the virtual NAS.
![Private Cloud NAS Dashboard with no services and New NAS Service button]()
NEW NAS Services
3. Click **New NAS Service** to open a recipe that is used to create the new NAS service.
![Private Cloud New NAS Service recipe form with VM Recipe Instance fields]()
VM Recipe Instance
This recipe only deploys NAS appliances for Private Cloud.
4. Complete the following information:
* Enter a ****Name**** for the new NAS Service.
* The default setting for ****Cores**** is 4.
* The default setting for ****RAM**** is 4 GB
8 GB of RAM is required for antivirus to be enabled. If fewer than 8 GB of RAM are used, then a warning message appears. The message can be disabled, or the RAM can be set to 8 GB. The antivirus only protects the computers connected to the NAS, which is done by scanning the files on the volume. Some users may decide to keep the Antivirus and some users may decide to use less RAM. The system-defined-default ****Cluster**** is automatically selected.
* Select the ****Network**** on which the NAS should run. Options include Internal and External networks.
* Select ****IP Address Type**** for the NAS Service.
* Select **Static**
Consult the IP Plan in your MacStadium Portal account to determine an IP Address that does not conflict with existing machines.
* Define a ****Hostname**** for the NAS Service VM.
* **OPTIONAL**: Enter a ****domain.**** (If the Domain field is left blank, the system defaults the domain to **workgroup**.)
* ****Timezone**** defaults to the default time zone.
* The **default** ****NTP Servers**** setting is recommended. This defines the Network Time Protocol (NTP) servers list, which is used for keeping the NAS service time synchronized.
* **OPTIONAL**: Enter the address of a ****Remote Syslog server.****
* **OPTIONAL**: Enter a ****Remote Syslog Template.****
4. Click **Submit**, and the NAS appears in the **NAS Service list**.
![Private Cloud NAS Service list showing the newly created NAS service]()
Newly Created NAS Service
5. To disable the **Antivirus** checkbox, deselect the checkmark and the **Antivirus Settings** box opens.
![Private Cloud NAS Service settings with Antivirus checkbox]()
Antivirus Checkbox
6. Uncheck the box and click **Submit**.
![Private Cloud Antivirus Settings dialog with Submit button]()
Antivirus Setting
7. Double-click the **Service** to bring up the Dashboard for the Service.
8. Select **Power On** to start the NAS.
![Private Cloud NAS Service dashboard with Power On button]()
Power On
9. Click the **Yes** to confirm power on.
To utilize the NAS service, at least one **Volume** needs to be implemented. A NAS service consists of one or more Volumes. Each Volume is a separate directory structure with its own settings for security, snapshots, storage tier, max size, antivirus, and sharing.
10. The next step is to create a NAS User.
### Create a NAS User
1. From the Main Dashboard, select **NAS**.
2. Select **NAS Services** → **Select a Service**.
![Private Cloud NAS Services list with a service to select]()
Select a Service
3. Double-click a Service.
![Private Cloud NAS Service detail showing NAS User option]()
NAS User
4. Select **NAS User**.
![Private Cloud NAS Service Users tab]()
NAS User
5. Select **New** to add a new NAS User. (This page is also used to edit or delete a user.)
![Private Cloud New NAS User form with username and password fields]()
NAS User
This is per service. For every virtual NAS appliance, there must be a set of users assigned to it.
* Required: **Username**
* Required: **Password**
* Optional: **Display Name**
* Optional: **Description**
* Optional: **Home Share**
* Optional: **Home Drive Letter**
6. Click **Submit**.
![Private Cloud NAS Users list showing the newly created user]()
New User
7. The next step is to create a Volume.
## Volumes
A NAS service consists of one or more Volumes. Each Volume is a separate directory structure with its own settings for security, snapshots, storage tier, max size, antivirus, and sharing. Multiple volumes can be set up on the NAS, and the size of the volume determines the space available to deploy files on the NAS.
Volume-level snapshots allow for customizing snapshot schedule and retention rules per individual NAS volume and provide the option for a quiesced snapshot. (Non-quiesced NAS volumes can be imported from Cloud snapshots to be used for restore.)
Quiesced volume snapshots freeze file system during the snapshot process. The Quiesce option can be selected when taking a manual volume snapshot and can be enabled within the snapshot profile for automated snapshots.
### About Volumes
There are two types of Volumes:
* **Local Volumes** are file systems stored within Private Cloud and consume storage in the vSAN. Each local volume can have different sharing, syncing, tiering, and permission settings.
* **Remote Volumes** are external file systems that are mounted to the VergeIO system and presented as if local.
### Creating Local Volumes
1. From the Main Dashboard, select **NAS**.
2. Select **Volumes** from the left menu.
![Private Cloud left menu with Volumes option highlighted]()
Volumes
When the NAS is first created, one volume (for log files) is automatically created.
2. Select **New** from the left menu.
![Private Cloud Volumes page with New button in left menu]()
New
3. Select the appropriate ****NAS Service**** from the dropdown list.
![Private Cloud New Volume form with NAS Service dropdown]()
NAS Service
* Enter a ****Name**** for the volume (required).
Spaces are not permitted.
* Enter a ****Description**** for the volume (optional).
* In the ****Filesystem Type**** dropdown list, select **Local Volume (EXT4)**.
* The ****Encrypt Volume**** option can be selected to encrypt the entire volume (AES-XTS).
**Encryption Considerations**
* **Encryption selection is only available during creation**; a volume cannot be changed from encrypted to unencrypted or vice-versa after creation.
* **Minor to moderate performance implications** are involved with enabling volume encryption.
* The **original encryption key** (defined when creating the volume) is needed for the lifetime of the volume; this encryption key must be **entered each time the volume is brought online** (for example, after disabling/enabling a volume or after its NAS service is rebooted).
* **Without the encryption key, it is not possible to bring the volume back online.**
4. Click **Submit.**
5. The next step is to create a Share (NFS or CIFS).
## Shares: NFS and CIFS
Network File System (NFS) and Common Internet File System (CIFS) are both file access protocols that allow client systems to access files on remote devices.
### About NFS and CIFS
* NFS uses a lightweight protocol with less overhead, which results in faster file access and transfer speeds.
* CIFS has more protocol overhead due to its support for various Windows-specific features. This can impact performance, especially in high-latency networks.
MacStadium recommends using CIFS.
### Creating a CIFS Share on an Existing Volume
CIFS (Common Internet File System) is a network protocol that allows clients to communicate with servers and access file sharing and print services as if they were stored locally. CIFS offers strong security features, which make it suitable for secure environments. It is important in Private Cloud because it allows access to a NAS volume over CIFS/SMB.
1. Navigate to the **NAS Dashboard**.
2. Click **New CIFS Shares**.
![Private Cloud NAS Dashboard with New CIFS Shares button]()
New CIFS Shares
3. In the **CIFS Shares** screen enter the necessary information.
![Private Cloud CIFS Shares form with Name, Share Path, and permissions fields]()
CIFS Shares
* Required: Enter a **Name** for the CIFS share.
* Optional: **Share Path** can be entered to define a specific path within the Volume; **otherwise**, this field **can be left blank** to share the entire Volume.
* Optional: A **Description** can be entered for the Share to record additional information about the Share.
* Optional: A **Comment** can be entered for the Share.
* Optional: A **Valid Users** list can be specified. This defines the users that are allowed to connect to the Share.
* Optional: A **Valid Groups** list can be specified. Users of the specified groups are allowed connection to the Share.
* Optional: **Allowed Hosts** field is to define one or more hosts that are permitted to access the Share. Hostname, IP address, domain name, netgroup, and subnet are all valid entries.
* Optional: **Denied Hosts** field is to define one or more hosts that are NOT permitted access to the Share. **Hostname, IP address, domain name, netgroup, and subnet are all valid entries.**
* Optional: **Read-Only** option can be selected to deny any write operations via this Share.
* **Browseable** option can be selected to make the Share visible in lists of available shares. **This option is disabled by default**.
Optional: **Users / Admin Groups** allow is to grant administrative privileges to the Share. This means that all file operations will be done as the super-user (root). Use this option carefully, as those in the list can do anything on the Share, regardless of individual file permissions.
* Optional: **User / Force Group** options can be specified to define a user or group used for all file operations performed via this Share.
* Optional: **Configuration Options** (advanced samba share options) can be specified to handle special-case scenarios.
3. Click **Submit**.
![Private Cloud NAS CIFS Shares list showing the newly created share]()
Newly Created CIFS Share
### Creating a NFS File Share on an Existing Volume
1. From the Main Dashboard, select **NAS**.
![Private Cloud left sidebar with NAS option highlighted]()
NAS
2. Select **Volumes**.
![Private Cloud NAS left menu with Volumes option highlighted]()
Volumes
3. Select the **Volume**.
![Private Cloud Volumes list with a volume row highlighted]()
View
4. Select **View**.
![Private Cloud Volume detail page showing NFS Shares and other options]()
Volumes
5. Select **NFS Shares**.
![Private Cloud Volume NFS Shares tab]()
NFS Shares
6. Select **New** to create a new share.
![Private Cloud NFS Shares page with New button]()
New
* Enter a Name for the share
* Enter a Share Path to define a specific path within the volume
* Enter a Description for the share
* Select Allow Everyone to allow all hosts, or specify one or more allowed hosts
* Select a Data Access option
* Select a User/Group Squashing option
7. Click **Submit**.
## Connecting to the Share
Now that the NAS Service, Volume, Users, and Share are created, end users can map to the shared drive from their Mac mini or other devices on the network.
# Private Cloud VM restorable snapshots
Source: https://docs.macstadium.com/iaas/storage/restorable-snapshots
Create and restore point-in-time snapshots of MacStadium Private Cloud VMs or entire instances. Supports both scheduled and on-demand snapshot management.
## Snapshots
A snapshot is a restorable point-in-time copy of a VM or Private Cloud storage. Snapshots can be used to revert either individual virtual machines, or an entire Private Cloud instance back to the snapshotted state. Snapshots can be run either as part of a schedule or on-demand.
Snapshots are particularly useful in the event of a misconfigured environment, as restoring from a cloud snapshot can revert the entire environment to its previous state.
There are two types of snapshots:
* **Cloud Snapshot**: a snapshot of an entire Private Cloud instance.
* **VM Snapshot**: a snapshot of an individual Virtual Machine.
### Snapshot Profiles
Snapshots are created by using snapshot profiles. Once a snapshot profile is set up, it can be set to automatically snapshot machines on a regular basis according to stored schedules. The retention period, frequency, and machines snapshotted are all configurable. A snapshot profile can be assigned to an entire Private Cloud, an individual VM, or a NAS volume.
Private Cloud includes multiple default snapshot profiles that can be used out of the box or modified as needed. You can also create new snapshot profiles from scratch.
**Default Snapshot Profiles**
Default profiles are readily available and can be modified if needed. The following are default snapshot profiles:
* **SOX (Sarbanes-Oxley)**
* Yearly snapshots retained for 7 years
* Monthly snapshots retained for 1 year
* Weekly snapshots retained for 31 days
* Daily snapshots retained for 7 days
* **HIPAA (Health Insurance Portability & Accountability Act)**
* Yearly snapshots retained indefinitely (no expiration)
* Monthly snapshots retained for 1 year
* Weekly snapshots retained for 31 days
* Daily snapshots retained for 7 days
* **NAS Volume Syncs**
* Daily (at 6pm) snapshots retained for 3 days
* **Cloud Snapshots** (suggested default profile for entire-system snapshots)
* Hourly for 3 hours
* Daily (at midnight) snapshots retained for 3 days
* Daily (at noon) snapshots retained for 1 day
Any of the default profiles can be modified to meet individual needs or requirements.
### Using a Default Snapshot Profile
1. Click **System**.
![Private Cloud main dashboard with System option in left menu]()
2. Click **Snapshot Profiles** and a list of default snapshot profiles appears.
![Private Cloud System menu with Snapshot Profiles option]()
3. In this example, we'll show the SOX profile, which was created for compliance focused orgs, but MacStadium recommends Cloud Snapshots for normal use cases.
![Private Cloud Snapshot Profiles list showing SOX and other default profiles]()
4. Double-click SOX row, and the **SOX Snapshot Profile** opens.
![Private Cloud SOX Snapshot Profile detail showing four snapshot periods]()
The default SOX snapshot profile has 4 periods:
* A snapshot is taken Daily. It is retained for 7 Days.
* A snapshot is taken Weekly. It is retained for 4 Weeks.
* A snapshot is taken Monthly. It is retained for 1 year.
* A snapshot is taken Yearly. It is retained for 7 years.
There is a **+ Add Period** button, which can be used to add more snapshots. For example, a user might want an hourly snapshot or a 6-hour snapshot. The retention time can also be set.
5. In this example, click **+ Add Period** to modify the existing default snapshot profile. The **Snapshot Profile Period** screen opens.
![Private Cloud Snapshot Profile Period form with frequency and retention fields]()
In this example, an hourly snapshot profile is created and the retention period is 3 days. This means every hour a snapshot is taken, and then it is kept for 3 days, causing 72 snapshots to be stored.
6. Click **Submit** to create the new snapshot profile.
![Private Cloud SOX Snapshot Profile updated with Hourly, Daily, Weekly, Monthly, and Yearly periods]()
This snapshot profile now has the following snapshots:
* Hourly
* Daily
* Weekly
* Monthly
* Yearly
Depending on individual needs and circumstances, this snapshot might be capturing too much or too little data. But it is important to remember that snapshots can be modified as needed, and starting with a default snapshot profile might be helpful.
For new users who do not have any snapshot profiles assigned, MacStadium recommends enabling the default Cloud Snapshots profile for Cloud snapshots. This profile stores 3 days of snapshots at varying frequencies, enabling recovery to a recent state in the event of a misconfiguration.
### Cloud Snapshots
The Cloud Snapshot profile determines the schedule used for creating snapshots of the entire system. MacStadium recommends setting a Cloud Snapshot profile for most Private Cloud instances.
Scheduled Cloud Snapshots are disabled by default. To enable cloud snapshots, navigate to **System → Cloud Snapshots** and select the snapshot profile to use.
If a Cloud Level Snapshot is configured, individual VM snapshots may not be needed. Cloud Snapshots include every VM and volume in a Private Cloud instance, and are taken in addition to VM snapshots.
#### Enabling Cloud Snapshots
1. From the main dashboard, click **System** on the left menu.
![Private Cloud main dashboard with System option in left menu]()
2. Click **Cloud Snapshots** from the left menu and you'll see the list of Snapshots.
![Private Cloud Cloud Snapshots list page]()
![Private Cloud Cloud Snapshots page showing no profile selected]()
3. Click **Select Snapshot Profile** from the left menu.
![Private Cloud Cloud Snapshots left menu with Select Snapshot Profile option]()
4. Select desired **snapshot profile** from the dropdown list.
* The default Cloud Snapshots profile is recommended as a starting point for Cloud Snapshots.
5. Click **Submit** at the bottom of the page.
![Private Cloud Select Snapshot Profile form with dropdown and Submit button]()
Once a Cloud Snapshot has been created, it can be viewed by clicking **Snapshot → Cloud Snapshots.**
![Private Cloud Cloud Snapshots list showing a newly created snapshot entry]()
### Manually Creating a Cloud Snapshot
1. From the main dashboard, click **System** from the left menu.
2. Select **Cloud Snapshots**.
3. Select **New** from the left menu.
![Private Cloud Cloud Snapshots left menu with New option]()
4. Fill in the form:
* **Name** (required): enter a name for the snapshot.
* **Description** (optional): enter a description.
* **Expires**: select a date and time for expiration.
* **Expiration Type**: you can select **Never Expire**, but this is not recommended. Snapshots without an expiration can consume substantial amounts of storage.
![Private Cloud New Cloud Snapshot form with Name, Description, and Expires fields]()
5. The **Private** checkbox is selected by default. This option pertains to multitenancy and can be ignored in most cases.
6. Click **Submit**.
### Managing Profiles for Scheduled Snapshots
These profiles pertain to any snapshot that uses them.
1. From the main dashboard, click **System** from the left menu.
![Private Cloud main dashboard with System option in left menu]()
2. Click **Snapshot Profiles** from the left menu.
![Private Cloud System menu with Snapshot Profiles option highlighted]()
3. Click the desired snapshot profile.
![Private Cloud Snapshot Profiles list with a profile row highlighted]()
4. Click **View**.
![Private Cloud Snapshot Profile dashboard showing periods and edit options]()
The dashboard for the selected profile opens.
* To add periods to the profile click the **+Add Period** link. (A snapshot profile can contain multiple periods.)
* To modify an existing period: click the (pencil icon) to the far right.
* To remove existing periods: click the (trash can icon) to the far right.
# Creating a New VM Manually
Source: https://docs.macstadium.com/iaas/x86-vms-private-cloud-vms/creating-a-new-vm-manually
Create a Private Cloud VM manually using an uploaded ISO. Used for OS versions not available as recipes. More effort than recipe-based deployment.
In addition to deploying VMs using recipes, virtual machines may also be created manually. This is primarily done when specific versions of OSes are required (for instance, desktop versions of Windows). Manually deployed VMs take additional effort to configure when compared to deployments from recipe. MacStadium recommends the use of recipes for VM deployment whenever possible.
## Uploading Images
For manually created VMs, guest operating systems are installed by adding a CD-ROM device with media file set to a bootable install ISO. Install ISOs are stored in the Media Images repository.
To upload an ISO for installation:
1. Select **Machines → Media Images**.
![Private Cloud sidebar with Media Images option selected]()
*Media Images*
2. The **Media Images** page shows stored install disk and uploaded VM images. There are two ways to upload images for install:
* Upload from URL - Private Cloud downloads the image from a remote URL
* Upload - The image is uploaded from the connected desktop
In this example, we will use Ubuntu Server as the install image.
## Upload from URL
Upload from URL is the recommended approach, as Private Cloud can often download images faster directly from the repository.
3. Find a direct link for the install media for the desired OS. In this case, Ubuntu only offers direct links through their mirror, so we'll select Alternative downloads, and get the URL from a mirror.
![Ubuntu Server download page showing Alternative downloads option]()
*Example: Ubuntu Server Download*
![Ubuntu mirror download page with direct ISO links]()
*Direct Download links from Mirror*
4. Upload the image to Private Cloud from the mirror. Return to the **Media Images** pages.
5. Select **Upload from URL**.
![Private Cloud Media Images page with Upload from URL button]()
*Upload from URL*
6. The **Upload from URL** dialog box opens.
![Private Cloud Upload from URL dialog box]()
*Upload from URL*
7. Paste the download link into the **Upload from URL** page.
![Private Cloud Upload from URL field with download link pasted]()
Copy Link
8. Click **Submit**, and the **Upload Process** begins.
![Private Cloud Media Images page showing upload progress]()
*Upload Process*
## Upload Directly
1. To upload an ISO from the connected computer, choose Upload on the Media Images screen. The **Upload Files** screen appears.
![Private Cloud Upload Files screen for local ISO upload]()
Upload Files Screen
2. Click **Upload**, and the **Upload Process** begins.
![Private Cloud Media Images page showing direct upload progress]()
Upload Process
# Creating a New VM with a Recipe
Source: https://docs.macstadium.com/iaas/x86-vms-private-cloud-vms/creating-a-new-vm-with-a-recipe
Create a Private Cloud VM from a MacStadium recipe: a template that pre-configures OS, apps, network, and storage. Recommended over manual VM creation.
You can create a new VM using a predefined recipe. Recipes are VM image templates that allow the automated creation of a new preconfigured VM with the selected operating system, applications, and configuration information. Recipes are quick and convenient, and may be preloaded with various software configurations.
To enable configuration, recipes include questions about each instance, such as the desired network configuration, username and password, in addition to standard VM parameters such as drive size or amount of RAM.
MacStadium recommends using a recipe when deploying a new VM, especially for users new to this process. Recipes ensure that VMs are configured optimally for operation within Private Cloud, and are much faster to install and deploy when compared to manual VM creation.
1. Select **Machines Dashboard → Virtual Machines.**
2. Click **New VM**.
![Private Cloud Machines Dashboard with New VM button]()
*New VM*
3. The *Select Type* tab opens. The left-hand side of the screen contains a list of options (Operating Systems, Services, and so on.) The right-hand side of the screen contains a list of recipes.
![Private Cloud Select Type tab showing OS recipes list with Ubuntu Server highlighted]()
*EXAMPLE - > Existing Recipe, for Ubuntu Server (recommended)*
MacStadium recommends using a preexisting recipe if one exists for the OS you need. Recipes always install the latest version of the selected OS in an optimal configuration with minimal post-installation configuration required. If a recipe does not exist for your OS, select **New VM** and use the template to create a new recipe.
4. In this example, select the recipe for **Ubuntu Server 24.04** and click **Next.**
5. The *Virtual Machine Setting* tab opens.
![Private Cloud Virtual Machine Settings tab with recipe fields]()
*Virtual Machine Settings Tab*
6. In the *VM Recipe Instance* box, complete the following fields:
* **Name** - the machine name used for management inside Private Cloud
* **Cores** - specifies the number of vCPUs allocated to this machine
* **RAM** - specifies the amount of RAM allocated to this machine
* **Cluster** - specifies the compute cluster to deploy the machine to. This should be left as *Default*.
* **Hostname** - the network hostname for the machine
![Private Cloud VM Recipe Instance fields showing Name, Cores, RAM, Cluster, and Hostname]()
*VM Recipe Instance*
7. In the Network box, you must select **Static** from the dropdown box. You must also select the correct **Network** from the dropdown list in order to ensure connectivity to existing MacStadium infrastructure. Otherwise, Private Cloud will provision a new isolated network for the VM.
![Private Cloud Network section with Static IP type and network dropdown]()
*Network*
Do not use DHCP as the IP Address Type when connecting VMs to existing networks. While DHCP is the default setting for IP Address Type, MacStadium Mac infrastructure is deployed with static IPs, and no DHCP server is present. **In order for network connectivity to work for deployed VMs on MacStadium networks, an IP must be set manually using the Static IP Address Type.**
8. In the *Static IP Configuration* box, all fields must be completed. However, the **auto** option in the IP Address field does not work. Complete the following fields:
* **IP Address** – Specifies the IP address of the server. The default is **auto, this is an invalid option for the static IP**. Consult the IP Plan in your MacStadium Portal account to determine an IP Address that doesn't conflict with existing machines.
* **Subnet Mask** – Specifies the range used for the subnet. This is in CIDR notation. The most common selection is '/24'
* **Default Gateway** – Specifies the IP to use for routed external traffic. This should be listed in the IP Plan
* **Nameservers** – Specifies the DNS servers to use for name resolution. This is not optional, and must be completed in order to resolve hostnames.
The default IP Address is Auto, however, this option does not work. **You must select an IP Address that is not currently being used by your machine, in the subnet of the network you are connected to.** Please consult the MacStadium *IP Plan*. the private subnet, the client can have on reserve, addresses near the end of the subnet. A subnet of 10.254.232.0/24, for example, can reserve address range, 10.254.232.200 through 10.254.232.250 for VMs.
This only works for customers who will not use the entire subnet for bare metal hosts. In the Drives box, select the *OS Drive Size* and *OS Drive Tier*. The *OS Drive Tier* specifies the tier of storage to deploy to, currently, only Tier 2 is available.
![Private Cloud Drives section showing OS Drive Size and OS Drive Tier fields]()
*Drives*
9. In the User Configuration box, complete the following fields:
* **User Name** – the desired username for the default user on the server
* **Password** – the desired password for the default user on the server
* **Confirm Password**
Or
* **Provide an SSH Key** – optional, enables SSH key authentication for the default user
![Private Cloud User Configuration section with username, password, and SSH key fields]()
*User Configuration*
10. Click **Submit**.
11. The new VM screen (*Ubuntu Server* , in this case) opens and the drives will begin to initialize. This may take a few minutes to complete, as Private Cloud will fetch the latest disk image for the selected operating system if an update is available. During this time, the Drive status will be listed as *Importing*.
![Private Cloud new VM screen with drive status showing Importing]()
*New VM Screen*
12. Once the drive has finished importing, the status will change to *Offline.* At this point, the machine is initialized and ready to be powered on.
![Private Cloud VM screen with drive status showing Offline and ready to launch]()
*Offline = Ready to Launch*
13. Click the **Power** button and the *Confirmation box* opens. Click **Power On**.
![Private Cloud Power On confirmation dialog]()
*Power On*
14. Open the Console by clicking the **Console** button.
![Private Cloud VM page with Console button highlighted]()
Console Button
15. When the Console opens, the disk boots and stops at a login prompt. Shortly after, the machine will start to download the latest available software updates.
![Private Cloud console showing Ubuntu Server login prompt]()
Console
For the majority of Linux virtual machine recipes, the Console is configured to appear as a text terminal. This makes copy/pasting text much easier, and enables easy access to terminal history.
# Manual Windows Installation
Source: https://docs.macstadium.com/iaas/x86-vms-private-cloud-vms/manual-windows-installation
Windows does not include Virtio drivers by default. These drivers need to be installed from a mounted disk during Windows installation.
Windows does not include Virtio drivers by default. These drivers need to be installed from a mounted disk during Windows installation.
For Windows Server installation, MacStadium highly recommends the use of the Windows Server recipe.
1. Windows requires additional drivers in order to access Private Cloud's virtualized storage and network hardware. To install a Windows VM manually, select **Machines Dashboard → Virtual Machines.**
2. Click **New VM**.
![Private Cloud Machines Dashboard with New VM button]()
New VM
3. The *Select Type* tab opens. The left-hand side of the screen contains a list of options (Operating Systems, Services, and so on.) The right-hand side of the screen contains a list of recipes. Select **New VM** and click **Next**.
![Private Cloud Select Type tab with New VM option selected]()
Next
4. The *Virtual Machine Setting* tab opens.
![Private Cloud Virtual Machine Settings tab]()
Virtual Settings Tab
5. In the *VM Recipe Instance* box, complete the following fields:
* **Name**
* **Cores**
* **RAM**
* **Cluster** (can be left as *Default*)
* **OS Family** = Windows
* **Attach Virtio Drives** = checked
![Private Cloud VM Recipe Instance fields with Attach Virtio Drives checkbox checked]()
VM Recipe Instance
Make sure the **Attach Virtio Drivers** checkbox is selected. This is required to install the Windows operating system.
A Windows Install ISO must be uploaded to Media Images before installation.
6. In the Drives box, make sure the **Create CD-ROM Drive** is set to **Use Local Media Image**. Select an uploaded Windows install ISO.
![Private Cloud Drives section with CD-ROM Drive set to Use Local Media Image]()
*Drives*
7. In the Network box, set the **NIC Interface** to **Virtio**, and the **Attach Network Interface** to **Internal**.
![Private Cloud Network section with NIC Interface set to Virtio and Internal network selected]()
Network
8. Click **Submit**.
![Private Cloud Virtual Machine Settings completed and ready to submit]()
Virtual Machine Settings
9. In the **New VM (Windows)** page, click **Power**.
![Private Cloud New VM page with Power button highlighted]()
10. In the **Confirmation** box, click Power On.
![Private Cloud Power On confirmation dialog]()
*Power On*
11. Open the **Console** by clicking the **Console** button.
![Private Cloud VM page with Console button highlighted]()
*Console Button*
12. When prompted, press any key to begin installation.
13. The **Windows** screen opens, click **Next**.
![Windows setup language and region screen]()
*Windows*
14. Click **Install Now**.
![Windows setup screen with Install Now button]()
*Install Now*
15. Accept the license terms and click **Next.**
![Windows setup license terms screen]()
*Advanced*
16. Select **Custom: Install Windows Only (advanced)**.![Windows setup installation type selection with Custom option]()
*Custom*
17. The installation will fail to find any drives. At this point, the virtio storage drivers need to be loaded to continue the install. Click **Load Driver**.
![Windows setup Where to install screen with no drives found and Load Driver button]()
*Load Driver*
18. Click **OK**.
![Windows Load Driver browse dialog]()
OK
19. Select the driver for the corresponding Windows version, according to the folder name. For example, the Windows 10 driver is located in E:\amd64\w10\\.
![Windows driver selection list showing Virtio SCSI drivers by OS version]()
Windows 10 Driver
20. Windows begins to install. Allow the installation to finish. Network connectivity does not work during the install, this is expected, as Windows does not come with Virtio network drivers.
![Windows setup installation progress bar]()
Installing Windows
21. Once installed, additional drivers need to be installed to allow network connectivity. To do this, open Explorer, and navigate to This PC. A CD drive with Virtio drivers should be accessible.
![Windows Explorer showing This PC with Virtio drivers CD drive]()
*CD*
22. **Double click** on **virtio-win-gt-x64**.
![Windows Explorer with virtio-win-gt-x64 installer file highlighted]()
*File Name*
23. When the **Setup Wizard** opens, click **Next**.
![Virtio Windows Guest Tools Setup Wizard welcome screen]()
*Wizard*
24. Accept the **terms** and click **Next**.
![Virtio Windows Guest Tools license terms screen]()
*Terms*
25\. Choose all and click **Next**.
*![Virtio Windows Guest Tools component selection screen with all options selected]()
*
*Select All*
26. Click **Install** to begin the installation.
![Virtio Windows Guest Tools ready to install screen with Install button]()
*Install*
27. The progress bar appears.
![Virtio Windows Guest Tools installation progress bar]()
*Progress Bar*
28. Click **Finish** to complete the Setup Wizard.
![Virtio Windows Guest Tools Setup Wizard completion screen with Finish button]()
Finish
29. Install **Guest tools** by clicking on the file **virtio-win-guest-tools**. Then accept the **license terms** and click **Install**.
![Virtio guest tools installer with Install button]()
*Install*
30. The progress bar appears.
![Virtio guest tools installation progress bar]()
Progress Bar
31. Click **Close** to complete the installation. Windows is now ready for use.
![Virtio guest tools installation complete screen with Close button]()
*Close*
# Private Cloud x86 VMs
Source: https://docs.macstadium.com/iaas/x86-vms-private-cloud-vms/private-cloud-x86-vms
Provision Windows and Linux x86 VMs on MacStadium Private Cloud with reserved vCPU, RAM, and storage. Managed via the Machines Dashboard.
## About private cloud
Private Cloud enables you to provision non-Mac VMs using reserved compute and storage resources. Non-Mac VMs are essential in enabling certain parts of scalable build systems on Mac, such as caching servers.
MacStadium Private Cloud is built on multi-tenant shared cloud infrastructure. You can pay for fixed amounts of isolated compute/storage/networking resources and deploy any combination of virtual machines with their desired configuration. Private Cloud also has network access to Mac infrastructure, allowing the use of non-Mac virtual machines in tandem with Mac compute resources.
## Overview
With Private Cloud, you can purchase an allocation of Virtual CPU, Virtual RAM, and Storage and manage the deployment of those resources using Private Cloud's dashboard.
![Private Cloud Machines Dashboard showing VM cluster statistics and storage usage]()
The Machines Dashboard displays the statistics for the VMs in a cluster. It also displays storage usage as well as machines that are not in use.
# VM Creation and OS Installation
Source: https://docs.macstadium.com/iaas/x86-vms-private-cloud-vms/vm-creation-and-os-installation
How to create a new VM manually in MacStadium Private Cloud: configure VM settings, attach an ISO, set a static IP, and install the OS via console.
Before following these steps, you need a bootable ISO uploaded to your cluster's Media Images repository. If you haven't done that yet, follow the steps in [Creating a New VM Manually](/iaas/x86-vms-private-cloud-vms/creating-a-new-vm-manually) under the **Uploading Images** section, then return here.
1. Once the file completes the download process and the files appear in the **Media Images** page, Navigate to the **Machines Dashboard**.
2. Click **New VM**.
![Private Cloud Machines Dashboard with New VM button]()
*New VM*
3. On the *Select Type* tab, select **New VM** and click **Next.**
New VM is a blank recipe that allows for manual OS installation.
![Private Cloud Select Type tab with New VM option selected]()
Select Type Tab
4. The *Virtual Machine Settings* tab opens.
![Private Cloud Virtual Machine Settings tab]()
*Virtual Machine Settings Tab*
5. In the *VM Recipe Instance* box, complete the following fields:
* **Name**
* **Cores**
* **RAM**
* **Cluster** (can be left as *Default*)
* **OS Family**
![Private Cloud VM Recipe Instance fields showing Name, Cores, RAM, Cluster, and OS Family]()
*VM Recipe Instance*
It is important that the OS Family matches the OS type installed.
6. In the Drives box:
* **Create a CD-Rom Drive**, select *Use Local Media Image*
* **Attach Selected iso to CD-ROM**, select the file that was previously uploaded into Media Images
* **OS Drive Interface**, select *Virtio-SCSI*
*![Private Cloud Drives section with CD-ROM Drive and OS Drive Interface settings]()
*
*Drives*
7. In the Network box, make sure the Create Network Interface is checked and select the interface from the dropdown.
![Private Cloud Network section with Create Network Interface checked]()
*Network*
Unlike OS Recipe templates, manually created VMs require that IP configuration be done at the OS level, and cannot be configured when deploying the VM.
8. Click **Submit**.
![Private Cloud Virtual Machine Settings with Submit button]()
*Submit*
9. The new VM screen opens. Click the **Power** button and the *Confirmation box* opens.
10. Click **Power On**.
![Private Cloud Power On confirmation dialog]()
*Power On*
11. Next, the OS must be installed and configured. To access the machine, click **Console**.
![Private Cloud VM page with Console button highlighted]()
*Console Button*
12. The **Console** opens.
![Private Cloud console showing VM display output]()
*Console*
Manually deployed VMs use a virtual screen, rather than a virtual terminal, meaning that text cannot be copied from the terminal.
13. Use the console to install the OS as usual.
14. The IP address configuration must be set manually as a part of installation. The process for this can differ, depending on the OS installed. In this example, we are setting a manual IP address for Ubuntu Server 24.04:
![Ubuntu Server network configuration screen with manual IP address fields]()
*Manual IP Address Assignment*
DHCP is not supported. An IP address must be manually assigned, using a free IP address on the IP plan. All fields must be completed to ensure network connectivity.
15. Complete the installation as usual. Most Linux distributions include drivers for Virtio, which is required for optimal performance when virtualizing hardware.
# Windows 2022 Installation
Source: https://docs.macstadium.com/iaas/x86-vms-private-cloud-vms/windows-2022-installation
Install Windows 2022 on MacStadium Private Cloud. Recipes handle ISO download and driver setup automatically; manual installation is also documented.
* Installing Windows 2022 from a recipe is easy and downloads the correct ISO, which starts with the right drivers. MacStadium recommends using a recipe to install Windows 2022.
![Private Cloud New VM dialog with Windows 2022 recipe selected]()
*Windows 2022*
# Add a new user to your MacStadium account
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/add-a-new-user
Invite team members to your MacStadium account, assign roles, and manage user-specific permissions from the MacStadium Portal's account management settings.
From the MacStadium Portal, you can add multiple team members to your account and apply user-specific permissions. You can grant access to only certain parts of the portal. For example, you can [add someone in the accounting department to the account](https://portal.macstadium.com/team-members) and allow them to see only accounting-related sections.
**Accounts with SSO enabled:** If your organization uses [SAML single sign-on](/macstadium/account-management-and-saml/saml-sso), access to your MacStadium account is controlled by your identity provider, and team members can't be added from the portal. To add a new user, ask your IT team to grant them access to the MacStadium application in your identity provider (for example, by adding them to the appropriate group). Their portal account is set up automatically the first time they [log in with SSO](/macstadium/account-management-and-saml/first-time-sso-login-to-macstadium-portal).
To add another team member to the MacStadium account:
1. Log in to the MacStadium Portal.
2. Click the person icon in the top right corner and select **Team Member**.
3. Click **New Team Member** to add a user.
## Required Items for Adding a Team Member
* Name
* Email address
* Role
* Phone Number (optional)
## Password Generation
Once you add a new team member, MacStadium sends an activation link to the specified email address. The new team member can use this link to set their password.
## Permissions
From the Team Member page, click **Edit** to update information and permissions.
You can archive a team member or view all archived people from this page. To view all archived team members click the Show Archived checkbox.
### IMPORTANT: Avoid Duplicate Accounts
Check with an admin before creating a new user account.
Creating a new user account locks the email to that new account and requires a support ticket to fix. If an account is accidentally created, then ask the Admin to file a support ticket under the correct account.
# Enable SAML SSO with Microsoft Entra ID
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/enable-saml-sso-with-azure-active-directory
Set up SAML SSO for the MacStadium Portal with Microsoft Entra ID (Azure AD): create the enterprise app, configure SAML, and share metadata.
## About
SAML SSO is a paid offering. Contact your account team through the [Customer Portal](https://portal.macstadium.com) for more information.
MacStadium does not support IdP-initiated logins. After SSO is configured, all users must log in at [portal.macstadium.com/sso](https://portal.macstadium.com/sso) using the ID provided by the MacStadium team.
You can also log in directly at [portal.macstadium.com](https://portal.macstadium.com/login).
## Overview
SAML SSO with Microsoft Entra ID allows customers to:
* Enable users to be automatically signed in to MacStadium using their Entra ID accounts.
* Manage accounts in one central location: Microsoft Entra ID.
## Getting Started
1. Open **Entra ID admin**.
2. Navigate to **Enterprise applications**.\\
![Azure Entra ID admin left sidebar with Enterprise applications option]()
3. Create a new application by clicking **New Application**.\\
![Azure Enterprise applications list with New Application button]()
4. Create an application by clicking **Create your own application**.\\
![Azure Browse gallery page with Create your own application button]()
* Enter a name (for example **MacStadium-Portal**).
* Select **Integrate any other application you don’t find in the gallery (Non-gallery).**\\
![Azure Create your own application form with name field and non-gallery option selected]()
5. Click **Single sign-on**.\\
![Azure enterprise app overview with Single sign-on option in sidebar]()
6. Select **SAML**.\\
![Azure Single sign-on method selection with SAML option highlighted]()
7. Click **Edit** on the *Basic SAML settings.*\\
![Azure SAML-based Sign-on page showing Basic SAML Configuration section with Edit button]()
8. Configure the SAML settings:
* **Identifier (Entity ID):** `urn:amazon:cognito:sp:us-east-1_pusi8jHs1`
* **Reply URL (Assertion Consumer Service URL):** `https://idp.macstadium.com/saml2/idpresponse`
* **Logout URL (Optional):** `https://idp.macstadium.com/saml2/logout`
* Click **Save**
![Azure Basic SAML Configuration with Entity ID, Reply URL, and Logout URL fields completed]()
9. Edit **Attributes & Claims** for your SAML app. The email field must be mapped to `user.mail` or login will fail.\\
![Azure Attributes and Claims configuration with email mapped to user.mail]()
Once configured properly, section 2 of your SAML app should look like the below screenshot.\\
![Azure SAML app section 2 showing correctly configured Attributes and Claims]()
10. Once the attributes & claims are updated, please provide our support team with the app federation metadata URL. You can copy the federation metadata URL in section 3 of your SAML app, as shown in the below screenshot.\\
![Azure SAML app section 3 showing App Federation Metadata URL to copy]()
# Enable SAML SSO with Google Workspace Federation
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/enable-saml-sso-with-google-workspace-federation
Configure SAML SSO for MacStadium Portal via Google Workspace. Create a custom SAML app in Google Admin, download metadata, and send it to MacStadium.
SAML SSO is a paid offering. Contact your account team through the [Customer Portal](https://portal.macstadium.com) for more information.
MacStadium does not support IdP-initiated logins. After SSO is configured, all users must log in at [portal.macstadium.com/sso](https://portal.macstadium.com/sso) using the ID provided by the MacStadium team.
1. Go to [Google Admin Console](https://admin.google.com/)
2. Navigate to “Web and mobile apps” (Apps → Web and mobile apps in the left menu or use [this link](https://admin.google.com/ac/apps/unified))\\
![Google Admin Console left menu with Web and mobile apps option highlighted]()
3. Create a new “Custom SAML App” (click Add app)\\
![Google Admin Web and mobile apps page with Add app dropdown showing Custom SAML app]()
4. Enter “App name” (e.g. MacStadium Portal)
5. Download the metadata by clicking Download Metadata - Keep this file for sharing with our support team later.\\
![Google SAML app setup with Download Metadata button]()
6. Configure
* **ACS URL:** `https://idp.macstadium.com/saml2/idpresponse`
* **Entity ID:** `urn:amazon:cognito:sp:us-east-1_pusi8jHs1`
* Configure email mapping with the "Show Advanced Settings" menu
* Select EMAIL for the Name ID Format field
* Select Primary Email for the Name ID field\\
![Google SAML app Service Provider Details with ACS URL, Entity ID, and Name ID fields]()
7. Map Primary email to email\\
![Google SAML app Attribute mapping with Primary Email mapped to email]()
8. Click Finish to complete the setup
9. Provide our support team with the metadata file from step 5
# Enable SAML SSO with Okta
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/enable-saml-sso-with-okta
Admin: configure SAML SSO for MacStadium Portal via Okta. Save the MacStadium certificate, configure the Okta app, and log in at portal.macstadium.com/sso.
## About
SAML SSO is a paid offering. Contact your account team through the [Customer Portal](https://portal.macstadium.com) for more information.
MacStadium does not support IdP-initiated logins. After SSO is configured, all users must log in at [portal.macstadium.com/sso](https://portal.macstadium.com/sso) using the ID provided by the MacStadium team.
You can also log in directly at [portal.macstadium.com](https://portal.macstadium.com/login).
## Overview
SAML SSO with Okta, allows customers to:
* Enable users to be automatically signed in to MacStadium using their Okta accounts.
* Manage users in one central location – Okta.
## Getting Started
1. Save the public signature key below (for example, save to `macstadium-us-east-1_pusi8jHs1.pem`)
`-----BEGIN CERTIFICATE----- MIICvDCCAaSgAwIBAgIIdQAHcexaNC4wDQYJKoZIhvcNAQELBQAwHjEcMBoGA1UE AwwTdXMtZWFzdC0xX3B1c2k4akhzMTAeFw0yNDAxMTAxNDEzMThaFw0zNDAxMTAw MDI1MThaMB4xHDAaBgNVBAMME3VzLWVhc3QtMV9wdXNpOGpIczEwggEiMA0GCSqG SIb3DQEBAQUAA4IBDwAwggEKAoIBAQDiLAh9YbRaJFwq6wODIsJixW9sCPVbO6MR wtSXEqDp1oRuJ//c7DVsytJd3koj1WRtF9+Hg1lvhx9Of+D0l5hjltB4mbeaQpOx cwgdxCepba2OuzxpU4APOCyU++NBfqe3Be+GIkWnbygsYFo5Dq26dFTSzYq/UNam YBTRgPh28k3yv82A2cH96wqwWGuLg52TUc56AGSCAwTCqN5VlwNaMzAuYqxHW2zo tmeLtC9T8q0vS+/UWq/EckR7jV/R4ziyEYB/PWgkZNUnOp0TCYtiuoYdHuqzoazW jhQjil9W0TsUq6k6Vo2ISz+r3XxlXXQMk6blmfJDU7JcMEkPZybhAgMBAAEwDQYJ KoZIhvcNAQELBQADggEBAJ8QzPsFgF/prkw2/qsgfAs0nKJY+zAaIqYSGZlYY4pq pObs0q2O8R3ecsS8e1cpahn4GdstPad69CqgyqPVf7EZm5ZMfUY9s5P7ufDJ3neh /YTp6KX1yHG8PJwJuCPSbB6OxcQirrxOKwsT2tPUMOziYHPQuickpJ7WlxEso3Xj QlcU+F4L8tjhxxF3/T7+fOlzZmivLcBPVx7z+21VoARhJvetoqCqzRccrOitHWye Bma/C6JOtvFq3JPWH0rgmAV6IGhvCSro4ANaToEmK7JYXiOD13DlA44P0l6gV7L8 p5EbQgF1F9eBQpfvL2E3Ml/+ZrXf5zBr5EjSLKvj/NE= -----END CERTIFICATE-----`
2. Open Okta admin.
3. Navigate to **Applications → Applications**.
4. Create a new **App integration** by clicking **Create App Integration**.
5. Select **SAML 2.0**.
![Okta Create a new app integration dialog with SAML 2.0 option selected]()
6. Click **Next**.
7. Enter app name (for example, **MacStadium-SAML**).
![Okta General Settings tab with app name field]()
8. Configure the SAML application.
9. Sign-on URL: `https://idp.macstadium.com/saml2/idpresponse`
10. Use this for Recipient URL and Destination URL: ✔︎ (make sure it’s checked)
11. Audience URI (SP Identity ID): `urn:amazon:cognito:sp:us-east-1_pusi8jHs1`
12. Click **Show Advanced Settings**.
13. Upload the public certificate `(macstadium-us-east-1_pusi8jHs1.pem)` from Step 1.
14. Single Logout.
15. Allow application to initiate Single Logout - ✔︎ (make sure it is checked)
16. Single Logout URL: `https://idp.macstadium.com/saml2/logout`
17. SP Issuer: `urn:amazon:cognito:sp:us-east-1_pusi8jHs1`
18. Attribute statements
![Okta SAML Settings with Attribute Statements section showing email mapping]()
19. Click **Finish** to complete the setup.
20. Provide the MacStadium support team the Metadata URL
![Okta app Sign On tab showing Metadata URL field to copy]()
# First-Time SSO Login to MacStadium Portal
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/first-time-sso-login-to-macstadium-portal
SSO login to the MacStadium portal with Okta, Azure AD, or Google Workspace. Your account admin must enable SSO before you can follow these steps.
This guide walks you through your first Single Sign-On (SSO) login to the MacStadium portal. If your organization has configured SSO authentication, you'll use your corporate identity provider credentials instead of a MacStadium-specific password.
## Prerequisites
Before beginning, ensure you have:
* An active MacStadium account with SSO enabled for your organization
* Access to your corporate email address (the one registered with MacStadium)
* Access to your organization's identity provider (e.g., Okta, Azure AD, Google Workspace)
* Credentials for your corporate identity provider
* A multi-factor authentication (MFA) device if one is required by your organization
* Confirmation email from MacStadium Support indicating SSO has been enabled for your account
**Important:** SSO must be configured by your MacStadium account administrator before you can use it. Contact your IT team or MacStadium Support if you're unsure whether SSO is enabled.
### Step-by-Step Login Process
#### 1: Navigate to the MacStadium Portal
* Open your web browser and go to: [**https://portal.macstadium.com**](https://portal.macstadium.com)
* You'll see the MacStadium login page
![portallogin.png]()
#### 2. Initiate SSO Login
* Enter your corporate email address in the email field
* Click the "Continue with SSO" button (or "Sign in with SSO" depending on your portal version)
* Do not enter a password; SSO authentication will redirect you to your identity provider
#### 3. Identity Provider Redirect
You'll be automatically redirected to your organization's identity provider login page. This may be:
* Okta
* Azure Active Directory / Microsoft Entra ID
* Google Workspace
* OneLogin
* Other enterprise identity providers
Note: The appearance of this page is controlled by your organization's IT team, not MacStadium.
#### 4. Authenticate with Your Identity Provider
* Enter your corporate credentials (username/email and password)
* Complete any multi-factor authentication (MFA) required by your organization
* This might include: authenticator app codes, SMS codes, biometric verification, or hardware tokens
* Click "Sign In" or the equivalent button on your identity provider's login page
### Understanding the "Abort or Proceed" Screen
After successfully authenticating with your identity provider, you may encounter an authorization consent screen that asks you to "Abort or Proceed". This screen appears because:
* First-time setup: Your identity provider is asking for permission to share your profile information with MacStadium
* Security verification: Your organization wants to confirm you intend to access an external service
* Attribute mapping: The identity provider needs consent to share specific user attributes (name, email, group memberships) with MacStadium
The authorization screen typically displays:
* The application requesting access: "MacStadium Portal" or your organization's custom app name
* Identity provider name: Your corporate identity system (e.g., "Contoso Azure AD")
* Permissions being requested:
* Read your basic profile information
* Access your email address
* View your group memberships (for role assignment)
You will then be provided with two options:
* Proceed / Allow / Continue - Authorizes access
* Abort / Cancel / Deny - Cancels the login attempt
### Which Option Should I Select?
#### Select "Proceed" if:
* You initiated this login attempt to access MacStadium services
* The application name shown is "MacStadium Portal" or your organization's custom SSO app
* You trust that your IT department has configured this integration
* You need to access your MacStadium infrastructure
#### Select "Abort" if:
* You did not initiate this login attempt (possible security issue)
* The application name looks suspicious or incorrect
* You're unsure whether your organization uses MacStadium
* You want to verify with your IT team before proceeding
#### When you click "Proceed":
* Authorization is granted, and your identity provider shares the necessary profile information with MacStadium.
* You will be automatically redirected, and returned to the MacStadium portal within 2-5 seconds.
* Upon successful login, you'll land on your MacStadium Portal dashboard.
* Additionally, your browser session will now be active and authenticated with SSO.
* For future logins, this consent is typically remembered, so you won't see the 'Abort/Proceed' screen again unless your organization's security policies require re-consenting to SSO login.
# SAML single sign-on for MacStadium accounts
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/saml-sso
Set up SAML SSO for your MacStadium organization to manage user authentication and access through your identity provider. Supports Okta, Azure AD, and Google.
## Introduction
The MacStadium SAML Single Sign-On (SSO) integration provides a secure and seamless way for your organization to manage user authentication and access within your MacStadium account. By integrating your MacStadium account with your existing Identity Provider (IdP), such as Okta or Azure AD, you achieve the following benefits:
* Centralized User Management: Use your existing IdP to manage user accounts across your organization, including access to MacStadium services.
* Streamlined Login Experience: Users authenticate once with your IdP and gain access to MacStadium resources without needing separate credentials.
* Enhanced Security: SAML-based authentication adds strong security. Enforce security policies like MFA (Multi-Factor Authentication) from your IdP.
SAML SSO is a paid offering. Contact your account team through the [portal](https://portal.macstadium.com) for more information.
## Key Components
The MacStadium SAML SSO integration involves these key components:
* MacStadium SSO Service: Our dedicated SSO service handles user management functions (login, password reset, etc.) and facilitates communication between your MacStadium account and your IdP.
* MacStadium Portal: Remains the front-end interface for users, interacting with the SSO service.
* MacStadium Portal is used for managing user roles. Orka 3.0 login actions also rely on the MacStadium Portal.
* External Identity Provider (IdP): Your chosen IdP (for example, Okta, Azure AD) handles user authentication.
## How It Works
1. **Configuration**: Your IdP Admin will configure your IdP to integrate with MacStadium and provide some metadata to our support staff to complete the integration. See the setup guides under Next Steps below.
2. **User Login**: A user attempts to access MacStadium resources.
3. **Redirection**: The MacStadium Portal redirects users to your IdP's login page.
4. **Authentication**: The user provides their credentials to your IdP.
5. **SAML Assertion**: Your IdP successfully authenticates the user and generates a SAML assertion containing user information. This is sent to the MacStadium SSO service.
6. **Verification and Authorization**: The MacStadium SSO service validates the SAML assertion and grants user access based on configured permissions.
## Supported Providers
The MacStadium SAML SSO integration works with major identity providers including:
* Okta
* Azure AD
* Google Workspace Federation
## Next Steps
Select your identity provider for step-by-step setup instructions:
* [Enable SAML SSO with Okta](/macstadium/account-management-and-saml/enable-saml-sso-with-okta)
* [Enable SAML SSO with Azure Active Directory](/macstadium/account-management-and-saml/enable-saml-sso-with-azure-active-directory)
* [Enable SAML SSO with Google Workspace](/macstadium/account-management-and-saml/enable-saml-sso-with-google-workspace-federation)
# Troubleshooting Credential Issues
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/troubleshooting-credential-issues
Fix MacStadium Portal and service credential issues: verify your email, reset your password, or find server credentials in the Portal under Services.
## Portal Login Issues
If you cannot log into the MacStadium portal:
* Verify you're using the correct email address
* Try resetting your password via the [MacStadium portal](https://portal.macstadium.com/), using the **Forgot Password** link on the login screen
* Contact your account administrator if you don't have access
## Service/Server Credential Issues
If your server or service credentials aren't working:
* Verify you're copying the password without extra spaces
* Check that the service is online and accessible
* Credentials can be viewed in Portal > Services > \[service] > Credentials
## Still Having Issues?
If you've tried the above and still can't connect, contact support with:
* Which service you're trying to access
* The error message you're receiving
* Whether this is a new setup or previously working
# Two-Factor Authentication (2FA)
Source: https://docs.macstadium.com/macstadium/account-management-and-saml/two-factor-authentication-2fa
MacStadium offers the ability for customers to enable two-factor authentication (2FA) when logging into portal.macstadium.com. Two-factor authentication.
## About
MacStadium offers the ability for customers to enable two-factor authentication (2FA) when logging into [portal.macstadium.com](https://portal.macstadium.com). Two-factor authentication provides customers with an additional layer of security when accessing environments.
## Overview
Two-factor authentication is available for anyone with Portal access.
2FA is NOT turned on by default. It is not required to log in to [portal.macstadium.com](https://portal.macstadium.com). It can easily be turned on/off from inside the Customer Portal.
## Getting Started
You must have an account in [portal.macstadium.com](https://portal.macstadium.com) to use two-factor authentication.
If there is no account in the Customer Portal, request one from an existing account administrator within your organization. For questions, email [support@macstadium.com](mailto:support@macstadium.com).
**Enabling Two-Factor Authentication:**
1. Log into [portal.macstadium.com](https://portal.macstadium.com).
2. Click your avatar in the top right corner.
3. Click **Users** from the dropdown.
4. Click **Security**.
5. Click **Enable Two-Factor Authentication**.
6. Click **Next**.
7. Open an authenticator app on a mobile device and scan the barcode.
An authenticator app can be downloaded from the Apple App Store or Google Play.
8. Enter the corresponding code provided by your authenticator app.
9. Two-factor authentication now changes to **Active** in the *Security* tab of the Portal.
## First Login After Enabling 2FA
On the next login, the sign-in screen looks different after entering your username and password:
1. Once authenticated, you are prompted to open your authenticator app.
2. The authenticator app provides a 6-digit code.
3. Enter the 6-digit code to gain access.
## Mandatory 2FA Enforcement
The Mandatory Two-Factor Authentication (2FA) Enforcement feature empowers administrators to enhance the security of user accounts by enforcing compulsory 2FA for all associated users. By enabling this functionality, administrators ensure an additional layer of protection for sensitive information and transactions within the Customer Portal.
This feature is accessible only to team members with Administrator roles. Mandatory 2FA is disabled by clicking the **Disable Mandatory 2FA** button.
2FA can be disabled by clicking the **Disable** button in the *Security* tab.
If there is a need to disable two-factor authentication, but access to the phone that was used to authenticate is missing, then:
1. Send a request to [support@macstadium.com](mailto:support@macstadium.com).
2. Give the Support Team the code used to enable 2FA.
3. The Support Team can remotely disable it.
4. Once it is turned off, login with the administrator *username* and *password*.
# Access and download MacStadium invoices
Source: https://docs.macstadium.com/macstadium/billing/accessing-invoices
Access PDF invoices for each MacStadium subscription in the MacStadium Portal under the Billing tab. Contact billing to consolidate multiple statements.
Invoices for your MacStadium subscriptions are available as PDFs in the [MacStadium portal](https://portal.macstadium.com/).
## How to Access Your Invoices
1. Log in to the [MacStadium portal](https://portal.macstadium.com/).
2. Click into the subscription you want to view.
3. Select the **Billing** tab in the subscription details.
4. Download your invoice as a PDF.
Each subscription generates its own invoice. If you have multiple subscriptions, you'll need to access each one individually.
## Consolidating Multiple Invoices
If you manage a large number of subscriptions and need consolidated billing, email [support@macstadium.com](mailto:support@macstadium.com) to request consolidation.
## Questions About a Charge
Email [support@macstadium.com](mailto:support@macstadium.com) and include your subscription ID and the invoice date.
# Canceling a MacStadium Subscription
Source: https://docs.macstadium.com/macstadium/billing/canceling-a-macstadium-subscription
How to cancel your MacStadium subscription: click Cancel Service in the portal. Servers go offline within 24 hours, no refund for the current period.
You don't need a lengthy contract to take advantage of Mac hosting at MacStadium. We bill on the first day of the month for the next 30 days of service. Your service will continue on a month-to-month basis until you cancel your subscription.
If you ever decide to leave MacStadium, you can do so through the [MacStadium Portal](https://portal.macstadium.com/). You can cancel a subscription at any time and for any reason.
When cancelling a subscription, the server is taken offline and all data is destroyed within 24 hours.
To cancel a single subscription, click into your machine's Details tab and then click the red Cancel Service button.
![MacStadium Portal subscription Details tab with Cancel Service button highlighted]()
If you have multiple subscriptions and want to cancel your account, please submit a [support](mailto:support@macstadium.com) ticket.
## Billing
If you cancel a subscription before the end of the current service period, you do NOT receive a refund for any amounts already paid for service in the future.
In accounting terms, MacStadium does not prorate services due to the man-hours required to return used hardware to inventory for re-use.
Servers become inactive when a subscription is cancelled and do not remain available through the end of the service period (subscription month). If you want to access your Macs until the end of the service period, cancel the service toward the end of the month, but before the next first-of-the-month billing occurs.
If you own the Mac on the canceled subscription (because you shipped it to us as part of our colocation service), then MacStadium will return your server to you after verifying the shipping address and speed of shipment requested. Our billing department will charge your payment method on file the actual shipping amount to close out your billing.
You're always welcome to return to MacStadium at any time with the same account.
# Fix a declined credit card on MacStadium
Source: https://docs.macstadium.com/macstadium/billing/credit-card-declined
MacStadium uses fraud protection that may flag legitimate transactions. If your card is blocked at signup, contact support to process your order manually.
MacStadium uses fraud protection services to identify and stop fraudulent transactions before they happen. These measures protect the security of our network and our customers.
In some cases, this protection may flag a legitimate transaction during signup. If that happens, you'll see:
**Unable to authorize your Credit Card. Please contact support via phone, chat, or open a ticket in the Customer Portal.**
You may see the same message if you try a second card. This does not mean the card itself is being declined by your bank.
## What to do
Contact [support@macstadium.com](mailto:support@macstadium.com) or open a ticket in the [MacStadium Portal](https://portal.macstadium.com/). Our team will process your order manually.
To speed things up, include the following details about the subscription you were trying to order:
* The data center location you selected
* The Mac hardware you want to subscribe to
* The operating system, if applicable
Once our team processes the order, you'll receive an activation email with access details when your server is online.
# MacStadium vendor onboarding and management
Source: https://docs.macstadium.com/macstadium/billing/vendor-management
Complete vendor onboarding for MacStadium by filling out the Zip vendor profile form and submitting it to the billing and legal teams for approval processing.
If you are onboarding to MacStadium as a vendor, please use the below link. Once you are finished, please send the file to [billing@macstadium.com](mailto:billing@macstadium.com), and [legal@macstadium.com](mailto:legal@macstadium.com).
[MacStadium Vendor Onboarding](https://app.ziphq.com/vendor-profile/verified/e964d1ce-99bc-4f93-aa08-e56cdc77b681)
# Acceptable Use Policy
Source: https://docs.macstadium.com/macstadium/legal-and-compliance/acceptable-use-policy
MacStadium Acceptable Use Policy (Exhibit B of the MSSA): prohibited actions and restrictions governing customer use of all MacStadium services.
## EXHIBIT B: Acceptable Use Policy
To protect the interests of MacStadium’s customers and ensure optimal Service Levels, MacStadium has developed this AUP, which applies to you and your Users of MacStadium’s Services. Use of any Services offered by MacStadium will constitute acknowledgment of and agreement to the terms outlined in this AUP. This AUP may be revised at any time at MacStadium’s discretion. Your continued use of MacStadium’s Services after such revisions will constitute your acceptance.
**1. PROHIBITED ACTIONS.** Customers may only use our servers and the Services for lawful purposes, in compliance with all applicable laws or regulations and in compliance with this AUP. In addition to the restrictions described in section 2.4 of the Agreement, activities that are specifically prohibited include, but are not limited to:
* Removing or modifying any program markings or any notice of MacStadium or its licensors’ proprietary rights (except when providing a SaaS offering to your Users).
* Making the Services, or any materials relating thereto, available in any manner to any third party for use in the third party’s business operations other than as otherwise expressly agreed upon between the Parties.
* Modify, make derivative works of, disassemble, reverse compile, or reverse engineer any part of the Services.
* Access or use the Services in order to build or support, or assist a third party in building or supporting, products, or services competitive to the Services in this Agreement.
* License, sell, rent, lease, transfer, assign, distribute, display, host, disclose, permit timesharing, or otherwise commercially exploit or make the Services, or related materials, available to any third party other than as part of a SaaS offering to your Users or as expressly permitted under the terms of this Agreement.
* Except as expressly provided herein, copy, reproduce, distribute, download, display, post or transmit any portion of the Services, in any form or by any means.
* Any attempt to gain unauthorized access to the Services or related systems or networks.
* Intentionally providing untruthful information regarding Customer’s identity as requested on any documentation required by MacStadium.
* Misrepresenting or fraudulently representing any products or services.
* Threatening harm to persons or property or otherwise harassing behavior.
* Abusing or harassing MacStadium employees, staff or agents, including without limitation, verbal harassment, yelling, swearing, rudeness, threats or any intentionally disruptive behavior.
* Managing a proxy server on MacStadium’s network
* Being subject to economic sanctions, prohibitions or restrictions on trade or export imposed by any governmental authority having jurisdiction over Customer or MacStadium, or in any jurisdiction where MacStadium or any of its affiliates are located, and regardless of whether the Services provided to Customer would violate such economic sanctions, prohibitions or restrictions.
* Interfering with the legitimate use by other customers or other third parties of resources on the MacStadium network or any of MacStadium’s Services.
* Storage, transmittal or use of any malicious code, such as viruses, worms, time bombs, Trojan horses and other harmful or malicious files, scripts, agents or programs.
* Mine bitcoins and other cryptocurrencies.
* Use the Services in any manner that would disparage MacStadium in any way.
**2. SPAM AND UNSOLICITED COMMERCIAL E-MAIL.** The Customer must comply with the CAN-SPAM Act of 2003 and all relevant regulations and legislation on bulk and commercial e-mail. MacStadium takes a zero-tolerance approach to the sending of mass Unsolicited Commercial E-mail (“UCE”) or spam over our network. UCE is any message where the primary purpose is commercial advertisement or promotion of a commercial product or service, which is sent to a recipient who has not requested it or opted out of such communication. In order to prevent unnecessary blacklisting due to spam, we reserve the right to occasionally sample bulk e-mail being sent from servers. The following activities are strictly prohibited:
* General Prohibitions. a) Using the MacStadium network to send or receive replies from UCE, hosting sites or information that is advertised by UCE from other networks, b) transmitting bulk e-mail through remote SOCKS, HTTP or other similar proxies who in turn make a SMTP connection to the destination mail servers, c) forging e-mail headers (i.e., ‘spoofing’), d) spamming using third-party proxy, aggregation of proxy lists, or proxy mailing software installation, and e) or hosting any web pages or providing any services that support spam.
* Landing Sites. The hosting of any web site or other content in any form intended to be intentionally or unintentionally retrieved or viewed by any recipient of any unsolicited email sent in violation of the terms defined in this AUP, whether sent from our network or any other network.
* Newsgroup Spamming. The posting of commercial messages to any newsgroup or discussion forum not chartered or organized for that specific purpose.
**3. U.S. DIGITAL MILLENNIUM COPYRIGHT ACT OR SIMILAR STATUTORY OBLIGATIONS.** To the extent a Customer uses the Services for hosting, advertising, sending electronic messages or for the creation and hosting of, or for posting material on, websites. Each Customer must a) comply with any notices received under Title II of the Digital Millennium Copyright Act of 1998 (Section 512 of the U.S. Copyright Act) or similar statute in other countries (the “DMCA”), b) set up a process to expeditiously respond to notices of alleged infringement that comply with the DMCA and to implement a DMCA-compliant repeat infringers policy, and c) comply with such processes and policy(ies). In appropriate circumstances, MacStadium will terminate the accounts of Customers who MacStadium suspects to be repeatedly or blatantly infringing copyrights. If MacStadium receives a notice alleging that Users are infringing another Party’s intellectual property, MacStadium may disable that Customer’s access to the Service or remove the alleged infringing material. If MacStadium receives more than one such notice for the same customer, MacStadium reserves the right to immediately terminate such Customer’s Subscriptions to the Services as deemed necessary by MacStadium to ensure continued protection under the safe harbor provisions under the DMCA or to prevent violations of other applicable laws or third parties’ rights.
**4. SYSTEM AND NETWORK SECURITY.** The Customer is required to protect the security of its internet accounts (e.g. ftp, e-mail, etc.) and usage to ensure the security of the MacStadium network and every MacStadium network object, including without limitation, routers, switches and workstations. Further, the Customer is responsible for validating the integrity of the information and data it receives or transmits over the internet and reporting any weaknesses in the MacStadium network and any incidents of possible misuse or violation of this AUP. To ensure the integrity of our network, the following activities are strictly prohibited:
* General Prohibitions. a) Using or distributing tools designed to compromise security, b) unauthorized monitoring of data or traffic on the MacStadium network or any other network without express authorization, deliberate attempts to overload the MacStadium network and broadcast attacks, and c) forging of any TCP-IP packet header or any part of the header information in an e-mail or intentionally or negligently transmitting files containing a computer virus or corrupted data.
* Denial of Service Attacks. The launching or facilitating the launch of a denial of service (“DoS”) attack on any host or computer on the MacStadium network for any reason whatsoever, or the use of any MacStadium network resource to interfere with the legitimate use by Customers or other authorized Users of resources of the MacStadium network or any other network. This includes the hosting of a Camfrog server or other server application that is a frequent target of DoS attacks or other types of attacks.
* Port Scanning. The scanning of the service ports of any host or computer on the MacStadium network or any other network, or the sniffing of packet traffic on the MacStadium network. The placing of any network interface into promiscuous mode is similarly prohibited.
* Unauthorized Access. Any unauthorized access to or unauthorized alteration of the files or operating system or other content of any host or network, any unauthorized attempt to obtain login credentials, such as username and/or password, of any host on the MacStadium network or any other network or any attempt to probe, scan or test the vulnerability of a system or network or to breach security or authentication measures.
* IRC Networks. The hosting of an IRC server that is part of or connected to another IRC network or server. Servers found to be connecting to or part of these networks will be immediately removed from our network without notice. The server will not be reconnected to the network until such time that Customer agrees to completely remove any and all traces of the IRC server and agree to let us have access to Customer’s server to confirm that the content has been completely removed.
**5. IP ALLOCATIONS.** All IP addresses which are assigned to Customer must be justified per ARIN Guidelines at [arin.net/policy/nrpm.html](https://www.arin.net/policy/nrpm.html). If it is determined that IP addresses which have been assigned to Customer are not being used in accordance with these guidelines, they may be revoked.
**6. IMMEDIATE THREATS.** If, in the reasonable determination of MacStadium, the equipment, software or hosted applications used by the Customer or the activities of the Customer poses an immediate threat to the physical integrity of MacStadium premises or the physical integrity or performance of the equipment or network of MacStadium or any other user of the premises, or poses an immediate threat to the safety of any person, then MacStadium may perform such work and take such other actions deemed necessary without prior notice to the Customer and without liability for damage to the equipment or data for any interruption of the Customer's (or its Customers') businesses. As soon as practical after performing such work, MacStadium will advise, by email, the Customer of the work performed or the action taken.
**7. MONITORING.** To determine compliance with this Agreement, MacStadium reserves the right to monitor Customer usage of the MacStadium network. Customer hereby consents to such monitoring and agrees that MacStadium is under no duty to monitor Customer use of MacStadium Services. For clarity, MacStadium will not have access to view any customer data as a part of any monitoring under this section.
**8. CUSTOMER’S RESPONSIBILITY FOR ITS USERS.** Any act or omission by a User will be a breach of this AUP if the act or omission committed by the User would be a breach of this AUP if committed by Customer.
**9. VIOLATION.** MacStadium may initiate an immediate investigation to substantiate the alleged violation. During the investigation, MacStadium may restrict Customer access to the network to prevent further violations. Any Customer violation of this AUP is left entirely to the reasonable discretion of MacStadium management. If a Customer is found to be in violation of this AUP, MacStadium may, at its sole and reasonable discretion, restrict, suspend or terminate such Customer's account. MacStadium has no obligation to provide warnings under any circumstances and can terminate the Customer’s account without prior notification upon a finding that the Customer has violated this AUP. Further, MacStadium may pursue civil remedies for any costs associated with the investigation of a substantiated AUP violation. MacStadium will notify law enforcement officials if\
the violation is believed to be a criminal offense and will cooperate fully with law enforcement authorities in investigating the alleged criminal offense.
# Copyright and Trademark Policy
Source: https://docs.macstadium.com/macstadium/legal-and-compliance/copyright-and-trademark-policy
MacStadium copyright and trademark policy: how to submit DMCA notices, report trademark infringement, and what happens after a report is filed.
## Reporting Claims of Copyright Infringement
At MacStadium, we respect the intellectual property rights of others and expect our users to do the same. Our Terms prohibit users from violating someone else’s intellectual property rights, including copyright and trademark.\
If you believe content that belongs to you is being used through our Service or MacStadium Site without your permission or users of our Service or MacStadium Site are selling counterfeit or infringing products, we want to know about it.
If you do submit a notice to us, please note that we may forward your notice, including your contact information, to the user who posted or used the content that you are complaining about. If you’re not sure whether content on one of our MacStadium Sites or sent through our Service infringes your intellectual property rights, then you may want to speak with legal counsel in your area before notifying us.
Finally, before submitting a notice you may want to reach out to the person or organization who posted or used the content you believe infringes your rights. You may be able to resolve the issue directly with that person or organization without contacting MacStadium.
## Copyright
Copyright law protects creative works like writings, music, pictures and photographs. Notices related to alleged copyright infringement may be submitted to us via email at the following email address: [legal@MacStadium.com](mailto:legal@MacStadium.com) When our Copyright Agent receives proper written notice (“DMCA Notice”) as described below, we will expeditiously remove or disable access to the allegedly infringing material and terminate the accounts of repeat infringers in accordance with the Online Copyright Infringement Limitation Act of the Digital Millennium Copyright Act (17 U.S.C. § 512) (“DMCA”).
Pursuant to the DMCA, your DMCA Notice must include substantially the following:
* The name, address, telephone number, and email address of the copyright owner;
* An identification or description of the copyrighted work that you claim is being infringed;
* A description of the content on our MacStadium Site or sent through our Service that you claim infringes your copyright;
* An identification of where the allegedly infringing content is located on our MacStadium Site or was sent through our Service (a URL works best);
* A statement that: (a) you have a good faith belief that the use isn’t authorized by the copyright owner, its agent or the law; (b) the information in your notice is accurate; and (c) under penalty of perjury, you are the owner or you are authorized to act on behalf of the copyright owner; and
* An electronic or physical signature from the copyright owner or someone authorized to act on their behalf.
The contact information for MacStadium’s designated agent for DMCA Notices of claimed copyright infringement is:
[legal@MacStadium.com](mailto:legal@MacStadium.com)
## Trademark
Trademark law protects words, designs, symbols, or phrases that an individual or company may use to identify and distinguish their goods or services from those offered by others. Examples of trademarks include word marks (“MacStadium”), logos, brand names, and slogans.
A trademark owner may be able to prevent others from using their trademark without their permission if the particular use is likely to cause confusion among consumers about who provides, endorses, or is affiliated with a product or service. Such a use may amount to trademark infringement. If the particular use of a trademark is an unauthorized use of a registered mark to reproduce fake, imitation, or “knock-off” goods, the use may also constitute trademark counterfeiting. Knowingly trading in counterfeit goods is illegal.
Notices related to alleged trademark infringement may be submitted to us via this form. When reporting a claim of trademark infringement, please ensure your notice includes the following:
* The name, address, telephone number, and email address of the trademark owner;
* Whether or not your claim involves the sale of counterfeit goods;
* An identification of the trademark that you claim is being counterfeited or infringed, including the trademark registration number, the country/jurisdiction where the trademark is registered, an identification of the category of goods and/or services covered by your registration, and a link to the registration or copies of your certificate of registration;
* A description of the content on our MacStadium Site or sent through our Service that you claim infringes your trademark or constitutes counterfeiting, including an explanation of how you believe the content is infringing or counterfeit;
* An identification of where the allegedly infringing or counterfeit content is located on our MacStadium Site or was sent through our Service (a URL works best);
* A statement that: (a) you have a good faith belief that the use isn’t authorized by the trademark owner, its agent or the law; (b) the information in your notice is accurate; and (c) under penalty of perjury, you are the owner or you are authorized to act on behalf of the trademark owner; and
* An electronic or physical signature from the trademark owner or someone authorized to act on their behalf.
This Copyright and Trademark Policy applies to the websites where MacStadium offers the Service, including the websites [macstadium.com](http://www.MacStadium.com), [orka.com](http://www.orka.com/), and [virtualcommand.com](http://www.virtualcommand.com/), as well as any other sites owned or operated by us (each a “MacStadium Site” and together the “MacStadium Sites”). This Policy also applies to all uses of our Service.
Updated September 24, 2021
# Master Services Agreement
Source: https://docs.macstadium.com/macstadium/legal-and-compliance/master-services-agreement
MacStadium Master Subscription Services Agreement v2.0: governing legal terms for all MacStadium services, referencing the SLA and Acceptable Use Policy.
# MacStadium Master Subscription Services Agreement (v.2.0 – Sept 26, 2025)
This Master Subscription Services Agreement (“**MSSA** ”) and any ordering document between Customer and MacStadium, Inc., (each, a “**Service Order** ”) and any other exhibit or addendum, constitute the “**Agreement** ” made and entered into by and between MacStadium, Inc., a Georgia corporation (“**Provider** ” or “**MacStadium** ”) and the Customer and/or its affiliates named below, (“**Customer** ”), as of the date fully executed herein (“**Effective Date** ”).
## 1. Agreement for Services
1. This MSSA, together with all applicable addendums and Schedules (each as defined hereafter), all of which are incorporated by this reference herein, states the terms and conditions by which Provider delivers and Customer accepts any or all of the services or licenses provided by Provider to Customer (each specific service or license, a “Service”). The definition of Service excludes “Non-MacStadium Services”). Specific terms and conditions applicable to each Service ordered by Customer are set out in separate one or more ordering document(s) referencing this MSSA (all such additional documents relating to a particular Service, including, without limitation, those identified as “service schedules” or “Service Orders,” collectively, a “Schedule”). The Schedules for the Services initially ordered by Customer may be set out in the appendices to this MSSA. The Schedules for any new Service ordered by Customer subsequent to the execution of this MSSA will be binding (i) when ordered electronically through the Provider’s web portal including a click-through acceptance of terms or (ii) contained in a Service Order signed by both parties and acknowledged and accepted in writing (including electronically) by Provider. The parties may enter into additional Schedules for additional Services from time to time. The parties may agree to modify any Services set out in any Schedule by executing a Service Order signed by both parties.
2. The Services may be provided as a service via the internet (“as a service”) or Software, as defined herein, in object code form, for installation and use on servers owned or controlled by the Customer (“on-premise”) for the term set forth in the Schedule. If the Services are provided as a service, then Customer is granted a non-exclusive and non-transferable right to access and use the Services for Customer’s internal business purposes as further described or limited in a Schedule. Use of the Services provided as a service via the internet is subject to Exhibit A – the Service Level Agreement (“SLA”) and Exhibit B – the Acceptable Use Policy (“AUP”). If the Services are provided for on-premise installation on servers owned or controlled by the Customer, then Customer is granted a non-exclusive and non-transferable license to use the Services for Customer’s internal business purposes as further described or limited in a Schedule. For all Services, Customer shall be entitled to receive support and maintenance as further described in the applicable Schedule.
3. Use of the Services is limited as provided in the Schedule. Customer shall reproduce all copyright, trademark or other proprietary rights notices on any copies of the Software and all documentation describing the operation of the Services (“Documentation”) and all such copies shall be subject to the terms, conditions and obligations under this Agreement. Customer shall not reverse engineer, reverse assemble, decompile, or disassemble the Services or otherwise attempt to derive, reconstruct, identify or discover any source code, underlying ideas, or algorithms of the Services by any means. Customer shall not modify, distribute, translate, or create derivative works based on the Services. The Services may not be sublicensed, distributed, leased, rented, offered as a service bureau or otherwise transferred to other third parties by the Customer. Customer may not use the third party software provided with the Services independent from its use of the Services. Customer may not the release to any third party the results of any benchmark testing of the Services. Customer may not authorize or permit any person or entity to do any of the foregoing.
4. Certain third-party applications, products or services that are provided by third-parties or Customer, including any third-party software licenses resold by MacStadium to Customer under a Service Order, that are integrated with, bundled with, and/or work in conjunction with the Service, such as by exchanging data with the Service or offering additional functionality within the Service (“Non-MacStadium Services”) may be available for Customer’s use with the Services. Non-MacStadium Services are not licensed by MacStadium as part of the Services, and MacStadium does not warrant or support Non-MacStadium Services, whether or not such products or services are designated by MacStadium as “certified”, “validated” or the like. Any exchange of data or other interaction between Customer and a provider of Non-MacStadium Services, is solely between Customer and such third-party provider. Customer’s use of Non-MacStadium Services and is subject to the terms and conditions provided by such third party, including without limitation, applicable end user license agreements and privacy policies, governing such use (“Third-Party Terms”). Customer agrees that it is solely responsible for complying with the Third-Party Terms, and that MacStadium is not responsible or liable for any Non-MacStadium Services or for any information or data that Customer may transmit, process or transfer to or from the Non-MacStadium Services, or for any claims caused by Non-MacStadium Services.
5. MacStadium shall have the right, upon reasonable prior written notice to Customer, to audit Customer's usage of the Software provided under this Agreement. Such audits shall be conducted during normal business hours and shall not unreasonably interfere with Customer’s business operations. If any audit reveals that Customer’s use of the Software exceeds the usage levels specified in the applicable Schedule, MacStadium shall have the right to invoice Customer for any overages at the rates specified in the Schedule or, if not specified, at MacStadium’s then-current standard rates for such overages. Customer agrees to pay all such invoiced amounts within thirty (30) days of receipt of the invoice. Additionally, if the audit reveals any underpayment of fees, Customer shall promptly remit payment to MacStadium for such underpaid amounts. The costs of the audit shall be borne by MacStadium unless the audit reveals an overage of more than five percent (5%) of the permitted usage levels, in which case Customer shall reimburse MacStadium for the reasonable costs of the audit.
## 2. Fees and Payment Terms
1. Customer shall pay to Provider all fees due for the Services according to the prices and terms listed in the Schedules. Except as otherwise set forth in a Schedule with respect to a particular Service, the prices listed in a Schedule will remain in effect during the Initial Term indicated in such Schedule. Provider reserves the right to change, upon thirty (30) days’ prior written notice to Customer, any fees it charges Customer for any Service provided during any subsequent Renewal Term. Customer may elect to not enter into a Renewal Term by providing written notice to Provider within thirty (30) days of the effective date of any Renewal Term. If no notice is received by the Provider, the Renewal Term shall become effective.
2. All fees and charges are due within thirty (30) days after Customer’s receipt of invoice therefor. All invoices from Provider are delivered via e-mail to an address specified and provided by Customer. Any invoiced charges not received when due will accrue interest at a rate of one and one-half percent (1.5%) per month, or the highest rate allowed by applicable law, whichever is lower. In addition to the foregoing and without prejudice to Provider’s other rights and remedies under this Agreement, at law or equity, if Customer is delinquent in its payments, Provider may, at Provider’s sole discretion do any one or more of the following: (i) terminate this Agreement pursuant to its terms; (ii) in whole or in part suspend providing Services (or any of them) to Customer until payment in full has been made to Provider or (iii) require other assurances to secure Customer's payment obligations hereunder.
3. All fees charged by Provider with respect to the Services are exclusive of taxes, VAT, and similar fees now in force or enacted in the future imposed on the transaction, all of which the Customer will be responsible for, except for taxes based on Provider’s net income.
## 3. Term; Termination
1. The term of this MSSA shall begin upon execution by both Customer and Provider and shall remain in effect until every Schedule hereunder has been terminated.
2. Each Schedule entered into by the parties pursuant to this Agreement shall be effective upon execution by both Customer and Provider and shall continue in full force and effect for the duration of the contract term specified in the Schedule (the “Initial Order Term”) and will thereafter renew in accordance with the terms of the applicable Service Order, unless terminated earlier in accordance with this Section 3 (subject to survival of the terms thereof as described in Section 3(e), below). Any renewal terms of a Schedule shall each be referred to as a “Renewal Term”.
3. Either party may terminate this Agreement or any subsequent Schedule if (i) the other party commits a material breach of this Agreement and fails to cure such breach within fifteen (15) days after written notice of the same, including Customer’s failure to pay any amounts when due.
4. Upon the effective date of termination of any Schedule: (i) Provider will immediately cease providing the Services set forth in such Schedule, and Customer shall immediately cease using such Services; (ii) all licenses granted hereunder with respect to the terminated Services will immediately terminate; and (iii) any and all payment obligations of Customer under such Schedule for Services provided through the date of termination will be due within thirty (30) days of the effective date of termination of such Schedule. Within thirty (30) days of termination of this Agreement as a whole, each party will return or certify the destruction of all Confidential Information (defined hereafter) of the other party in its possession and will not make or retain any copies of such Confidential Information, except as required (an only to the extent necessary) to comply with any applicable legal, archival or accounting recordkeeping requirement; provided, however, that all such retained data shall remain subject to the confidentiality provisions of Section 7 of this MSSA.
5. (i) Termination of the MSSA shall not serve to terminate any then-effective Schedule, and the terms of this MSSA and those of any Addendum or Schedule applicable to the Service(s) shall survive any termination of this MSSA or until termination of such Schedule(s); and (ii) termination of any Schedule shall not serve to terminate any other Schedule or the parties’ respective obligations thereunder. The definitions herein and the respective rights and obligations of the parties under Sections 3(c)-(d), 5(b), 6-8, 9, 11 and 12 shall survive any termination or expiration of this Agreement.
## 4. Customer Responsibilities
1. Customer shall designate a representative (the “Customer Manager”) who shall have overall responsibility for managing and coordinating Customer’s obligations hereunder and who has the authority to act for and bind Customer in connection with the Services. The Customer Manager shall serve as Provider’s initial point of contact for the resolution of issues in connection herewith, must be available to Provider during the Term and have authority to schedule performance of the Services and address any issues that may arise.
2. Customer will maintain the designation and authorization to access the Provider’s management portal (“Portal”), with all data and information reasonably necessary for Provider to perform the Services.
3. Customer shall provide and coordinate, in a timely manner, Provider’s authenticated access to any Customer network or system, such as custom firewall configurations (the “Customer System”), as necessary. Customer shall inform Provider in writing and in advance of the performance of any Services, of any security and access standards or requirements with respect thereto.
## 5. Warranties
1. Each party warrants and represents that: (i) it has the legal right to enter into this Agreement and perform its obligations hereunder; and (ii) the performance of its obligations hereunder will not violate any applicable U.S. laws or regulations or cause a breach of any agreements with any third parties. In addition, Customer represents and warrants that the performance of its obligations and use of the Services by Customer or its clients will not violate any applicable laws.
2. Provider further represents and warrants that (i) to the best of its knowledge and belief, it owns or otherwise has all necessary rights to provide the Services and the Software\[1] to Customer; (ii) the Services and Software perform in all material respects in accordance with the Documentation; and (iii) subject to Customer’s satisfaction of its obligations hereunder, it will perform the Services in a professional and workmanlike manner consistent with standard industry practices, and will use commercially reasonable efforts to prevent the transmission of any Trojan horse, malicious code, or other computer software code, routines or device designed to disable, damage, impair, erase or deactivate any data via the Provider’s networks or systems to the Customer System.
3. Customer represents and warrants to Provider that (i) Customer has the full right, power and authority to grant the rights granted herein and to provide Provider the Customer Data, access to the Customer configuration and network, and any other Customer-provided materials for Provider’s use; (ii) neither Provider’s access to or use of the Customer Data or the Customer System will: (A) give rise to any action or claim by a third party; or (B) cause Customer to breach any of its agreements or understandings in relation to the Customer Data or the Customer System, including without limitation any terms of use to which Customer is bound; (iii) the Customer Data will not contain any confidential or proprietary information of a third party that Customer does not have the right to provide; and (iv) Customer will use commercially reasonable efforts to prevent the transmission of any Trojan horse, malicious code, or other computer software code, routines or device designed to disable, damage, impair, erase or deactivate any data via the Customer System to Provider’s networks or systems.
4. EXCEPT FOR THE EXPRESS WARRANTIES SET FORTH HEREIN, THE SERVICES ARE PROVIDED EXCLUSIVELY ON AN “AS IS” BASIS, AND PROVIDER AND ITS SUPPLIERS DISCLAIM ANY AND ALL OTHER EXPRESS, IMPLIED AND STATUTORY WARRANTIES WITH RESPECT TO THE SERVICES, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, QUALITY, PERFORMANCE, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT AND TITLE. PROVIDER DOES NOT WARRANT THAT THE SERVICES WILL BE UNINTERRUPTED OR ERROR-FREE. PROVIDER DOES NOT WARRANT OR GUARANTEE ANY SPECIFIC RESULTS FROM CUSTOMER’S USE OF THE SERVICES. AS BETWEEN THE PARTIES, CUSTOMER SHALL BE SOLELY RESPONSIBLE FOR ENSURING THE ACCURACY OF ALL CUSTOMER DATA PROVIDED BY CUSTOMER IN CONNECTION WITH THE SERVICES.
\[1] “**Software** ” means the software (in source and object forms) and related documentation owned or licensed by Provider and furnished to or used by Customer under this Agreement in connection with the Service(s).
## 6. Limitation of Liability; Force Majeure
1. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, EXCEPT WITH RESPECT TO LIABILITY FOR CUSTOMER’S BREACH OF THE RESTRICTIONS SET FORTH IN SECTION 1(C) HEREOF, IN NO EVENT WILL EITHER PARTY BE LIABLE TO THE OTHER FOR CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, OR INDIRECT DAMAGES OR COSTS, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR REVENUES, LOSS OF DATA OR PROPERTY ARISING FROM ANY CLAIMS WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE AND STRICT TORT), OR OTHERWISE IN CONNECTION WITH THE SERVICES OR THIS AGREEMENT, EVEN IF THE OTHER PARTY, ITS AFFILIATES OR SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR COSTS.
2. Except WITH RESPECT TO LIABILITY FOR A PARTY’S GROSS NEGLIGENCE OR WILLFUL MISCONDUCT, CUSTOMER’S BREACH OF THE RESTRICTIONS SET FORTH IN SECTION 1(C) HEREOF, CUSTOMER’S FAILURE TO PAY THE FEES DUE HEREUNDER OR A PARTY’S BREACH OF SECTION 7 HEREOF, OR as may be otherwise set forth in a schedule with respect to a specific service, In no event will EITHER PARTY, its AFFILIATES or suppliers be liable to THE OTHER PARTY or any Users under this Agreement or otherwise, regardless of the form of claim or action, in an amount that is greater than the total fees received by Provider under this Agreement during the twelve (12) months immediately preceding the event GIVING rise to such claim or \$50,000 USD.
3. THE PARTIES ACKNOWLEDGE THAT PROVIDER HAS SET ITS PRICES AND ENTERED INTO THIS AGREEMENT IN RELIANCE UPON THE LIMITATIONS OF LIABILITY AND THE DISCLAIMERS OF WARRANTIES AND DAMAGES SET FORTH HEREIN, AND THAT THE SAME FORM AN ESSENTIAL BASIS OF THE BARGAIN BETWEEN THE PARTIES. THE PARTIES AGREE THAT THE LIMITATION AND EXCLUSIONS OF LIABILITY AND DISCLAIMERS SPECIFIED IN THIS AGREEMENT WILL SURVIVE AND APPLY EVEN IF FOUND TO HAVE FAILED OF THEIR ESSENTIAL PURPOSE.
4. Neither party shall be liable for and will not be responsible to the other for any delay or failure to perform under this Agreement if such delay or failure results from any act or cause beyond the reasonable control of the affected party. If either party is unable to perform under the Agreement because of the occurrence of an event of force majeure lasting more than thirty (30) days, then the other party may terminate the affected Service(s) and applicable Schedule(s) upon written notice to the other party.
## 7. Confidential Information; IP Rights
1. Each party acknowledges that it may have access to certain information deemed confidential by the other party, (collectively, “Confidential Information”), which shall expressly include, but not be limited to, Provider Technology\[1] (with respect to Provider) and certain Customer Data\[2] (with respect to Customer). Each party agrees that it will not use in any way, for its own account or the account of any third party, except as expressly permitted by, or to the limited extent required to achieve the purposes of, this Agreement, nor disclose to any third party (except as required by law or to such party’s employees, attorneys, accountants and other advisors as reasonably necessary), any Confidential Information of the other party. Each party will protect the confidentiality of the Confidential Information of the other party by employing the same measures (but in no event less than reasonable measures) as it takes to protect its own Confidential Information. The obligations of this Section 7 shall last during the term of the Agreement and for two (2) years after the term of the Agreement.
2. The receiving party may disclose Confidential Information pursuant to the requirements of a validly issued subpoena, governmental agency or by operation of law, provided that it gives the disclosing party, when practical and permitted, reasonable prior written notice sufficient to permit the disclosing party to contest such disclosure.
3. In the event of a violation or threat of violation by a party, directly or indirectly, of the terms of Section 7(a), the party who would be harmed by such violation, will have the right, and in addition to all other remedies available to it at law, in equity or under this Agreement, to affirmative or negative injunctive relief from a court of competent jurisdiction. Each party acknowledges that a violation of this section would cause irreparable harm and that all other remedies are inadequate.
4. In the event that Customer discloses personal data to Provider (“Personal Data”), Customer agrees (i) that Provider or its affiliate(s) may process such Personal Data consistent with applicable law and regulation, only for the purpose of the provision of Services by Provider to Customer or for purposes connected with the subject matter of the disclosure or business relationship between the parties; (ii) that such processing may include the transfer of such Personal Data to Provider’s affiliates or its storage in a local database; and (iii) that Customer will, to the extent required by applicable law, obtain all necessary consents to such processing from the data subjects concerned.
5. Neither party will publish or use any advertising, sales promotions, press releases or other publicity that uses the name, logo, trademarks, or service marks of the other without the prior written approval of the other, provided that Provider may list Customer as a customer.
6. Provider and its licensors shall retain all right, title, and interest (including copyright and other intellectual property rights or informational rights) in and to the Services and all legally protectable elements or derivative works thereof, including, without limitation, the Provider Technology.
\[1] “**Provider Technology** ” means Provider’s proprietary technology, including the Services, the Software, software tools, hardware designs, algorithms, user interface designs, architecture, class libraries, objects and documentation (both printed and electronic), network designs, trade secrets and any related intellectual property rights throughout the world (whether owned by Provider or licensed to Provider from a third party) and also including any derivatives, improvements, enhancements or extensions of Provider Technology conceived, reduced to practice, or developed during the term of this Agreement by either party.
\[2] “**Customer Data** ” means (i) information or data created or otherwise owned by Customer or any client of Customer or licensed by Customer from third parties used in conjunction with the Services; or (ii) information or data output generated by the Services that is based on information or data supplied by the Customer and is specific to the Customer.
## 8. Indemnification
1. Customer will indemnify, defend and hold Provider, its affiliates and their respective directors, officers, employees, agents, successors and assigns (each a “Provider Indemnitee”) harmless from and against any and all costs, liabilities, losses, and expenses (including, but not limited to, reasonable attorneys' fees and costs) payable to a third party (collectively, “Losses”) and resulting from any claim, suit, action, or proceeding (each, an “Action”) brought by any third party against a Provider Indemnitee arising out of Customer’s (i) breach of Section 5 of this MSSA; or (ii) negligence or willful misconduct.
2. Provider will indemnify, defend and hold harmless Customer, its affiliates and their respective directors, officers, employees, agents, successors and assigns (each a “Customer Indemnitee”) from and against any and all Losses resulting from any Action brought by any third party against a Customer Indemnitee arising out of (i) a breach of the warranty set forth in Section 5; or (ii) the gross negligence or willful misconduct of Provider. Notwithstanding the foregoing, Provider shall have no obligation under this Section 8 to the extent such Action is caused by (i) any use of the Services, Software or Data not in accordance with this Agreement; (ii) Customer’s failure to comply with Documentation (including, without limitation, any minimum requirements for use of the Services); (iii) any breach by Customer of its obligations under this Agreement; (iv) the operation, combination or use of Services, Software or Data, without Provider’s prior written consent, with products or services provided by Customer or third parties; (v) the modification of the Services, Software or Data by Customer, or (vi) Customer’s negligence, or willful misconduct.
3. Each party’s indemnification obligations under this Agreement (including, without limitation, any such obligations set forth in an applicable Schedule) shall be subject to: (i) receiving prompt written notice of the existence of any Action (provided, however, that failure to satisfy this condition shall relieve a party of its indemnification obligations only to the extent the indemnifying party is actually prejudiced thereby); (ii) being able to, at its option and expense, control the defense of such Action (provided, however, that the indemnifying party shall not, without the prior written consent of the indemnified party, settle any Action or otherwise consent to the entry of any order or judgment in any Action if such settlement, order or judgment admits any liability of the indemnified party or requires the indemnified party to take or to refrain from taking any action, other than the payment of damages); (iii) permitting the indemnified party to participate in the defense of any Action, at the indemnified party’s option and expense; and (iv) receiving full cooperation of the indemnified party in the defense thereof. In the event Customer notifies Provider of any Action against Customer or in the event Provider reasonably believe such an Action is likely, Provider may do one or more of the following: (x) to modify the Services in order to avoid an infringement; (y) if applicable or appropriate, to procure a license sufficient to continue offering the Services (including, without limitation, Customer’s use thereof); or (z) to terminate the applicable Service and refund to Customer the pre-paid Fees for the remaining portion of the term (provided that in the event of terminating the applicable Service, Provider shall continue to remain liable for its indemnification obligations).
## 9. Assignments
Neither this Agreement, nor a party’s obligations or rights hereunder, may be transferred or assigned by either party without the other party’s prior written consent; provided, however, that either party may assign this Agreement in whole, but not in part, without the other party’s consent to (a) any entity controlled by, under common control with, or controlling such party; (b) the successor-in-interest in any merger, share exchange or other reorganization; or (c) the purchaser of all or substantially all of such party’s assets. Any attempted assignment, transfer, or other disposition by a party in violation of this provision will be null, void and of no force and effect. This Agreement shall inure to the benefit of and be binding upon the permitted successors, legal representatives and assigns of the parties hereto.
## 10. Insurance
MacStadium will maintain sufficient insurance coverage for its assets and operating infrastructure that meets MacStadium’s obligations pursuant to this Agreement’s insurance types and limits and by law, with insurance carriers rated A- or better by A.M. Best Company. At all times during this Agreement, MacStadium will maintain the following coverage and limits:
1. Commercial general liability and contractual liability coverage insuring the activities of MacStadium for liabilities written on an occurrence basis, with limits of \$1,000,000.
2. Workers’ Compensation with limits no less than the minimum required by applicable law;
3. Employers’ Liability with limits of \$1,000,000.00 per occurrence.
4. Cyber liability insurance with limits of \$5,000,000 in the aggregate.
MacStadium may make reasonable changes to its insurance coverages from time to time and shall notify the Customer, at any time during this Agreement or any renewal, if the above-referenced limits are reduced.
## 11. General
This Agreement constitutes the exclusive statement of all mutual understandings between the parties with respect to the subject matter hereof, superseding all prior or contemporaneous proposals, communications, and understandings, oral or written. Each Schedule includes terms that are in addition to, and not in lieu of, this MSSA. The headings in this Agreement are provided for convenience only and will not affect its construction or interpretation.
The parties and their respective personnel are and shall be independent contractors, and neither party by virtue of this Agreement shall have any right, power, or authority to act or create any obligation, express or implied, on behalf of the other party.
This Agreement may only be amended in writing by the mutual consent of the parties. No waiver of any provision hereof or of any right or remedy hereunder shall be effective unless in writing and signed by the party against whom such waiver is sought to be enforced. No delay in exercising, no course of dealing with respect to, or no partial exercise of any right or remedy hereunder shall constitute a waiver of any other right or remedy, or future exercise thereof.
If any provision of this Agreement is determined to be invalid under any applicable law, it is to that extent to be deemed omitted, and the balance of the Agreement shall remain enforceable.
There shall be no third-party beneficiaries to this Agreement.
All notices shall be in writing and shall be deemed to be delivered when received by certified mail, postage prepaid, return receipt requested, or when sent by e-mail. All notices shall be directed to the parties at the respective addresses given above or to such other address as either party may, from time to time, designate by notice to the other party.
## 12. Governing Law
This Agreement and all obligations of the parties hereunder shall be interpreted, construed, and enforced in accordance with the laws of the State of Delaware, without regard to any conflict of laws rules or analyses. Any action or proceeding arising from or relating to this Agreement must be brought in a state or federal court having jurisdiction in Wilmington County, Delaware, and each party irrevocably submits to the jurisdiction and venue of any such court in any such action or proceeding and agrees to waive any defenses to venue and jurisdiction including forum non conveniens. The parties agree that the United Nations Convention on Contracts for the International Sale of Goods is specifically excluded from application to this Agreement.
## 13. Counterparts
This MSSA, any addendum, and any Schedule entered into hereunder may be executed in two or more counterparts, each of which shall be deemed an original and all of which together shall constitute one instrument. The parties may sign this MSSA, any Addendum, and any Schedule and deliver the signature pages via facsimile or electronic transmission (with the originals to follow) or otherwise in accordance with this Section 11 of this MSSA.
*Last Updated: Sept 26, 2025*
# MacStadium security and compliance overview
Source: https://docs.macstadium.com/macstadium/legal-and-compliance/security
Review MacStadium security policies, compliance certifications, and trust documentation. Visit trust.macstadium.com for current audit and compliance records.
**MacStadium adheres to the strictest standards when our customers' respective data is involved.**
Please visit [trust.macstadium.com](http://trust.macstadium.com/) for the most up-to-date records and explanations of the security and data compliance policies that MacStadium maintains.
# Service Level Agreement
Source: https://docs.macstadium.com/macstadium/legal-and-compliance/service-level-agreement
MacStadium guarantees 99.9% monthly uptime. This SLA defines what counts as an outage, how service credits are calculated, and how to file a claim.
**EXHIBIT A: Service Level Agreement**
This SLA constitutes MacStadium’s commitments regarding availability of the Services. This SLA is subject to change at MacStadium’s reasonable discretion. We will not apply the terms of a modified SLA during your Initial Service Term; however, upon renewal, the version of MacStadium’s SLA that is current at the time of renewal will apply throughout your Renewal Service Term(s).
## **SLA General Terms:**
### 1. DEFINITIONS
1.1 “Non-Compliance” shall mean any act or inaction by the Customer that is not in compliance with the material terms of this SLA.
1.2 “Outage” shall mean you are reasonably unable to conduct activities while using the Services. Outage does not mean Scheduled Maintenance or emergency maintenance.
1.3 “Service Credit” shall mean the monetary amount credited to you on the following months’ invoice for the affected Services following claim approval by MacStadium.
1.4 “Service Level” shall mean the monthly uptime percentage as described herein for the Services outside of emergency maintenance and Scheduled Maintenance.
1.5 “Severity” shall mean an assessment of the degree of impact to the Customer.
1.6 “Unavailable” or “Unavailability” shall mean whenever the availability of the Services does not meet the Service Level of at least 99.9% uptime in a calendar month as set forth in section 8.1 due to a failure of MacStadium’s infrastructure or systems that is wholly within MacStadium’s control.
### 2. MAINTENANCE
Scheduled Maintenance and emergency maintenance will not cause a loss of availability of the Services unless it is beyond the reasonable control of MacStadium. In any event, MacStadium shall use reasonable efforts to ensure any loss of availability arising from Scheduled Maintenance is limited to the shortest period of time practical and will not occur during the business hours where your data center is located. MacStadium may also perform emergency maintenance, including the installation of critical patches, as needed, but shall use reasonable efforts to notify you within four (4) hours of initiating such emergency maintenance. You can review all maintenance updates by visiting [status.macstadium.com](https://status.macstadium.com/). As a part of maintenance, MacStadium may install patches that address security vulnerabilities, but MacStadium will not be liable for any inability, delay, failure or omission in identifying the need for a security upgrade or patch, or for the implementation of any security upgrade or patch. MacStadium will coordinate with you for the application of any noncritical patches as they are released.
### 3. NOTIFICATION AND RESPONSE TIME
In the event of an incident that leads to the Unavailability or Non-Compliance, Customer shall notify MacStadium within seven (7) days of the date that the Unavailability or Non-Compliance occurred via submitting a ticket in the MacStadium management portal. MacStadium will respond to all Unavailability and Non-Compliance incidents in the shortest time feasible.
MacStadium cannot provide any specified resolution time(s) for any incident(s) before the incident occurs because we cannot accurately state the exact time frame each varying issue may require.
### 4. REQUEST FOR SERVICE CREDIT
After the incident has been remedied you MUST request a Service Credit from MacStadium in writing by submitting a ticket in the MacStadium management portal within seven (7) days. If you do not request a Service Credit in this manner, you WILL NOT be entitled to a Service Credit. MacStadium will evaluate all information reasonably available to us and use commercially reasonable efforts to process your claim to make a good faith determination of whether a Service Credit is owed.
### 5. EXCLUSIONS
Causes for Unavailability and Non-Compliance do not include: a) Scheduled or emergency Maintenance or a suspension of Services, b) a User’s data or content related other than to scalability or volume, c) the incompatibility of any operating system, application or vendor supplied security patches with a User’s data or content, d) your or your agents or representatives acts or omissions, including all of your or a third party’s testing of the servers, e) the failure of servers or services outside of a data center on which the Services are dependent, including, but not limited to, inaccessibility on the internet that is not caused by MacStadium’s network or network providers, f) MacStadium’s blocking of content that MacStadium deems in its sole discretion to be in violation of the AUP, g) any equipment or hardware downtime not hosted in MacStadium data centers, h) any force majeure event, as detailed in section 14.6 of the Agreement and any other circumstances, events, actions, or inactions not within MacStadium’s reasonable control, i) a denial of service attack or unauthorized access (i.e., hacking), k) your failure to meet the terms and conditions of this SLA, j) co-located devices, k) downtime not reported by you within seven (7) days of the day the downtime first began, l) time required to format or reformat disks or a RAID array, m) time required to load, reload, configure or reconfigure an operating system or applications, n) time required for Customer to restore from backup, and o) any customer initiated changes to their firewall.
### 6. LIMITATIONS
You shall not receive a Service Credit under the terms of this SLA if: a) you disable or block (either intentionally or unintentionally) MacStadium’s administrative access in any way that prevents MacStadium from performing its obligations, b) you make any modifications that prohibit a device from rebooting properly, c) you modify or delete the contents of MacStadium’s administrative directories, d) you disable or modify any software installed by MacStadium for the purposes of monitoring or server maintenance, e) you violate any material terms of this Agreement, f) you fail to request a Service Credit in the manner provided in this Agreement, and g) you have an undisputed balance in accounts receivable over sixty (60) days past due.
### 7. GENERAL
Notwithstanding anything to the contrary in this Agreement or any Service Order, the following provisions apply to all Services:
7.1 SOLE REMEDY. APPROVED SERVICE CREDITS ARE YOUR SOLE AND EXCLUSIVE REMEDY FOR ANY PERFORMANCE OR UNAVAILABILITY ISSUES FOR ANY SERVICES UNDER THIS AGREEMENT. YOU MAY NOT UNILATERALLY OFFSET ANY FEES FOR APPLICABLE SERVICES FOR ANY PERFORMANCE OR AVAILABILITY ISSUES.
7.2 Maximum Credit. In any calendar month the maximum Service Credit to which you shall be entitled\
shall NOT, under any circumstance, exceed the total amount of one (1) month’s fees for the applicable Services. For the avoidance of doubt, any approved Service Credit shall solely apply to the affected, specific of piece of infrastructure Services stated in the applicable Service Order. In no event, shall a Service Credit be awarded (i) for any unaffected infrastructure Services or (ii) that aggregates monthly fees from more than one (1) Service Order.
7.3 Verification. All periods of Unavailability and Non-Compliance must be verified by MacStadium, and approved Service Credits will be applied by MacStadium as a credit to be used towards a portion of your monthly fees on the following months’ invoice. The period of Unavailability or Non-Compliance is measured from your notification to MacStadium of the incident to the time the Unavailability or Non-Compliance has been remedied as confirmed by MacStadium.
7.4 Monitoring. MacStadium reserves the right to monitor certain protocols and configurations necessary to maintain the availability of the Services. The protocols required may include, but are not limited to, SNMP, API, and SSH. Monitoring may also require, but is not limited to, configuration changes to the Services, configuration, User accounts, service start sequence, and firewall. MacStadium may also passively access the infrastructure providing the Services via port scans and ICMP. End-users may opt-out or change these passive settings at any time. If Customer orders Orka® Services, Customer grants consent to MacStadium to troubleshoot any technical issues that may arise as a part of your Orka® Services. MacStadium shall promptly notify you if and when there is a need to troubleshoot. You have the right to withdraw consent upon ten (10) days prior written notice sent to MacStadium at [legal@macstadium.com](mailto:legal@macstadium.com); however, if you experience technical issues with Orka® that require troubleshooting, MacStadium will not be able to fix such issue until we receive your consent. Performance of any troubleshooting shall not degrade or materially change Orka® Services in any way.
## Service Specific Terms:
### 8. DESCRIPTION OF SERVICES & AVAILABILITY
MacStadium shall use commercially reasonable efforts to ensure meeting the Service Levels described herein. If you experience Unavailability, you may be entitled to a Service Credit upon MacStadium claim review. As a note, MacStadium is not a public cloud provider, nor do we offer public clouds for purchase. The Services provide a means for you to run your own cloud software environment. MacStadium recommends the placement of servers in two or more data centers as a preventative measure against the failure of a single data center.
8.1 Service Level. The Services shall have a Service Level of at least 99.9% uptime in a calendar month, which is calculated using the following formula:
Total Available Minutes in One Month – Outage time / Total Available Minutes in One Month x 100
8.2 Service Credits. The following Service Levels and Service Credits are applicable to Customer’s use of MacStadium Services including single bare metal Mac mini or Mac Pro, Mac private cloud services, and Orka® virtualization software:
| Availability | Service Credit |
| ------------ | -------------- |
| \<99.9% | 10% of the MRC |
| \<99.0% | 25% of the MRC |
| \<98.0% | 50% of the MRC |
# Viewing your environment in My Cloud
Source: https://docs.macstadium.com/macstadium/macstadium-overview/ip-plan
My Cloud in the MacStadium Portal shows your environment by data center: public servers, firewalls, VPN credentials, network allocations, and host assignments.
The **My Cloud** page in the MacStadium Portal is where you see the networking and access details for your environment, including VPN credentials, network ranges, firewall public IPs, and the IP assignments for your servers.
My Cloud replaces the IP Plan spreadsheet that was previously distributed. Other MacStadium docs may still refer to this information as "your IP Plan"; this is now under My Cloud.
## Open My Cloud
1. Sign in to the [MacStadium Portal](/macstadium/macstadium-overview/macstadium-portal) at [portal.macstadium.com](https://portal.macstadium.com/login).
2. Open **My Cloud**.
3. Select the data center tab for the environment you want to view (Atlanta, Las Vegas, or Dublin).
## What's on the page
My Cloud groups your environment by data center. For each data center you'll see:
* **Public Servers**: servers reachable on the public internet, with their public IPs and hostnames.
* **Firewalls**: each dedicated firewall has its own section, containing:
* **IP Allocation**: the networks behind the firewall, with subnet (CIDR), range, mask, and gateway.
* **Credentials**: username and password for [connecting to the environment via VPN](/orka/networking-with-orka-at-macstadium/vpn-connection), and (where provisioned) for **Harbor OCI Storage** and **Private Cloud**. Select **Show** to reveal, then copy.
* **Host Assignments**: servers assigned to each network, with their private IPs and (where applicable) public NAT IPs.
The firewall's public IP is the address you use as the VPN server address and as the on-prem peer when configuring a site-to-site VPN tunnel. See the setup guides for [AWS](/orka/networking-with-orka-at-macstadium/aws-orka-connections), [GCP](/orka/networking-with-orka-at-macstadium/gcp-orka-connections), or [Azure](/iaas/azure/site-to-site-vpn-configuration-with-azure).
## Working with servers
Whether you're looking under **Public Servers** or under a network's **Host Assignments**, each server shows the same information and shortcuts.
For every server you'll see its name, hardware type (for example, M2.M or M2.L), service ID, current status (such as **Active** or **Pending**), and IP address. If the server has more than one IP, you can expand the entry to see the rest.
You can also:
* **Launch VNC** to open a remote screen-sharing session to the server.
* **Copy SSH Address** to grab a ready-to-paste `ssh` command for the server.
* **Copy** the server's name, service ID, or IP with a single select.
* **Select the server's name** to open its full details, including any credentials for that server.
## Field reference
Other MacStadium docs refer to legacy field names from the old IP Plan spreadsheet. Use this mapping when you're looking them up in My Cloud:
| Looking for... | Find it in My Cloud |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| VPN server address, `FW1-Outside`, or the `Outside` network | The firewall's public IP, shown at the top of the firewall's section |
| VPN username and password | **Credentials** for that firewall |
| The `Private-1` network (or any internal network) | A row in the firewall's **IP Allocation** table. The **Subnet ID** column is the CIDR you'll need for VPN tunnels. |
Network names vary by environment. If your environment was provisioned with custom network names, use the **IP Allocation** table to identify the equivalent networks.
# MacStadium cloud hosting for Apple hardware
Source: https://docs.macstadium.com/macstadium/macstadium-overview/macstadium-overview
MacStadium hosts Apple hardware for enterprise: bare metal Macs, Orka macOS virtualization, and cloud access, in MacStadium data centers, AWS, or on-prem.
MacStadium enables organizations to achieve seamless macOS workload orchestration and virtualization at scale, whether for CI/CD build-and-test pipelines or full-fidelity virtual desktop environments. We deliver purpose-built software that integrates control-plane orchestration and hypervisor-level virtualization on Apple hardware, with deployment options available in our data centers, public cloud, or on-premises.
## Software Solutions
### Orka: macOS VM Orchestration & Virtualization
* **Control Plane**
* Centralized orchestration of macOS VMs
* k8s native to integrate with popular tooling
* Native CI plugins to support common tools like Jenkins, GitHub Actions, Bitrise, and more
* **Virtualization Engine**
* Lightweight hypervisor running on Mac nodes
* Rapid VM spin-up/down with dynamic resource allocation
* Built-in support for networking, storage attach, and hardware passthrough
### Citrix with MacStadium
* **VDI User Experience**\
Use Citrix DaaS to provide the desktop management and Orka to enable portable macOS VMs
## Deployment Flexibility
1. **Public Cloud**
1. Run our software on AWS with bare-metal Mac EC2 instances
2. Use managed Kubernetes services like Amazon EKS, Azure AKS, and Google GKE to orchestrate macOS workloads
2. **On-Premises**
1. Integrate with your existing data center Mac infrastructure
2. Use self-hosted or managed k8s systems to orchestrate macOS workloads
3. **Hosted by MacStadium**
1. Choose from one of our global data centers for turnkey management
## Bare Metal & IaaS
While our software is the focus, we continue to offer:
* **Mac Bare-Metal & IaaS**
* Dedicated Mac hardware on demand
* Private networks, firewalls, and storage expansion
* Non-mac compute for general-purpose use cases (Private Cloud Compute)
## Why MacStadium?
* **Apple-Native Expertise**\
Deep specialization in macOS virtualization and lifecycle operations
* **End-to-End Control**\
Full stack designed for macOS workloads, from Application-level APIs to hypervisor to hardware.
* **Scalable & Secure**\
Tenant isolation, private networking, and enterprise-grade SLAs
* **Choice & Portability**\
Consistent software across clouds, on-prem, or hosted environments
# MacStadium Portal for subscriptions and support
Source: https://docs.macstadium.com/macstadium/macstadium-overview/macstadium-portal
Manage MacStadium subscriptions and support at portal.macstadium.com. A business email is required to register; personal email domains are not accepted.
## Overview
The MacStadium Portal allows organizations to manage their MacStadium solutions and support tickets.
## Getting Started
Create your account and log into the Portal by going to [portal.macstadium.com](https://portal.macstadium.com/login)
## Business Email Requirement
MacStadium services are intended for business use, and as part of our onboarding process, we require a valid business email address to create an account.
If you attempt to sign up using a personal or non-business email, your registration will fail with the following error:
PreSignUp failed with error: Business email required.
To proceed, please use a company domain email address (e.g., `you@yourcompany.com`).
# Mac Configuration Assistance
Source: https://docs.macstadium.com/macstadium/support/mac-configuration-assistance
MacStadium Remote Hands Service covers basic hardware and OS setup to ensure access to the Mac via remote SSH, VNC, or screen sharing.
## About
MacStadium [Remote Hands Service](/macstadium/support/remote-hands-service) covers basic hardware and OS setup to ensure access to the Mac via remote SSH, VNC, or screen sharing.
## Overview
MacStadium is a fully-staffed service organization with technicians and engineers available around the clock - many of whom are highly trained on Apple hardware solutions.
## Getting Started
We will provide as much guidance as possible for customers in need of more specific help setting up the more detailed aspects of the OS or included software.
MacStadium is an infrastructure services provider, not an IT support organization. For this reason, we often refer more advanced support issues dealing with custom configuration of your OS or software to one of our partners who specialize in IT configuration and management.
# MacStadium Support Tiers
Source: https://docs.macstadium.com/macstadium/support/macstadium-support-tiers
MacStadium offers Basic, Pro, and Premium support. See response time SLAs, support hours, and what's included in professional services before you decide.
### Pricing and Support Comparison
| | **Basic** | **Pro** | **Premium** |
| ----------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Price** | Included (free) | 10% of Annual Spend | 20% of Annual Spend |
| **Recommended if** | You are developing or testing MacStadium out. | Extra support for growing businesses with mission-critical workflows. | MacStadium is essential to your business. Partner with us. |
| **Support hours** | 9am–5pm in the Data Center TZ | 24 x 7 | 24 x 7 |
| **Support channel** | Email, Portal | Email, Portal, Scheduled Phone Support (weekdays, 9–5pm) | Email, Portal, Scheduled Phone Support (weekdays, 9–5pm), and Dedicated Slack Channel |
| **Professional services\*** | | 5 hours/year to support onboarding or other updates. Additional service packages available for purchase. | 15 hours/year to support onboarding or other updates. Additional service packages available for purchase. |
| **Business Impact / First Response Time** | General usage question: \<2 business days
Environment Impacted: \<1 business day | General usage question: \<48 hours
Marginal impact: \<24 hours
Major impact: \<4 hours
Environment down/inaccessible: \<1 hour | General usage question: \<48 hours
Marginal impact: \<24 hours
Major impact: \<2 hours
Environment down/inaccessible: \<30 minutes |
| **Security and Service Agreements** | Access to Online Trust Center | Access to Online Trust Center
Customized MSA/DPA
Annual vendor security questionnaire | Access to Online Trust Center
Customized MSA/DPA
Annual vendor security questionnaire
Participation in customer's audit or tabletop exercises (up to 4 hours annually) |
| **Knowledge Base Access** | ✓ | ✓ | ✓ |
| **Online Trust Center Access** | ✓ | ✓ | ✓ |
| **Scheduled Phone Support\*\*** | ✗ | ✓ | ✓ |
| **Maintenance on Nights/Weekends\*\*\*** | ✗ | ✗ | ✓ |
| **Dedicated Slack Channel for Support** | ✗ | ✗ | ✓ |
**Notes**
* **\*Scheduled phone support:** MacStadium's support team is available for a phone call scheduled during EU and US working hours on weekdays from 9am-5pm. Applies to non-emergency calls scheduled via Calendly booking link in an open support ticket.
* **\*\*Maintenance on nights/weekends:** Customers on a Premium plan may request an alternative maintenance window to occur on nights and/or weekends instead of during US or EU working hours.
# MacStadium Remote Hands hardware support
Source: https://docs.macstadium.com/macstadium/support/remote-hands-service
MacStadium Remote Hands covers hardware diagnosis, network issues, OS password recovery, factory restore, and OS service changes on customer request.
The MacStadium *Remote Hands* Service covers the following issues:
* Mac hardware diagnosis and repair
* Network infrastructure or IP issues
* OS password recovery to default
* OS restore to factory default
* OS restore from backup (i.e. Time Machine)
* OS services enable/disable (turn off firewall, SIP, etc.)
MacStadium will always assist customers with a service request.
In some cases, a request may go beyond our *Remote Hands* service scope (i.e. items not listed above). For those instances, MacStadium will quote customers an hourly rate to address that specific issue. In other cases, MacStadium may refer a customer to one of our IT partners who might be better suited to address that specific IT concern.
MacStadium is not responsible for the backup of customer software.
# MacStadium support plans and services
Source: https://docs.macstadium.com/macstadium/support/support
Compare MacStadium support tiers: Business, Pro, and Premium, with 24/7 monitoring, Remote Hands, and engineering support for networking and virtualization.
## About Support
MacStadium offers various First-Line Support Services 24/7 for customers on the Business, Pro and Premium support plans including:
* Monitoring, that automatically opens support tickets
* Remote Hands and Basic Support (primarily for Host-Level issues)
* Shift manager to triage, evaluate severity, and escalate issues
## Overview
Severity definitions for cloud environments:
* **Severity 1** - Outage incident affecting multiple customers
* **Severity 2** - Outage incident affecting a single customer
* **Severity 3** - Non-outage incident that adversely affects one or more customers. For example, network latency.
* **Severity 4** - Non-outage incident related to a redundant component failure
* **Severity 5** - False alarm
### Advanced Engineering Support
Customers on the Business, Pro and Premium support plans can get 24/7 Engineering Team Support
* Networking, storage, and virtualization expertise
* Break/fix, upgrades, advice, troubleshooting
* Non-urgent tickets are worked in the order they are received
### 24/7 Off-Hours and On-Call Engineering Support
* 4-hour maximum response time for system unavailability (Severity 1 and Severity 2)
* Non-urgent issues handled 8 AM the next working day (Severity 3 to Severity 5)
## Getting Started
**MacStadium Ticketing System**
1. Start by logging in to [portal.macstadium.com](https://portal.macstadium.com)
2. Click **Support Center** in the bottom-left corner.
3. Click **Create Ticket** in the upper-right corner.
If the request is related to a specific subscription, then select it from the dropdown:
1. Select the appropriate ticket type.
2. Type a message in the text box.
3. (Optional) Attach files by clicking the paperclip icon in the bottom-left.
* If the ticket or attachment contains sensitive information such as login credentials, and so on, then click the checkbox marked, **sensitive information** to ensure the message is never stored or transmitted in plain-text (meaning, *via email*).
4. Click **Create Ticket** and the ticket is created, assigned a number, and added to the new ticket queue.
* You can review all tickets (open and closed), responses, and attachments via the same portal.
* You can close tickets by selecting **Closed** from the dropdown (beside the ticket number).
## Possible Reasons for Creating a Ticket
Creating a ticket through MacStadium's [customer portal](https://portal.macstadium.com/support-center/tickets) is the fastest and most secure way of reaching MacStadium engineering staff. Each ticket is immediately reviewed 24/7 by one of our customer support technicians. When necessary, tickets are escalated to more specialized engineering staff. Tickets are the best way to kick off most requests.
### Environment Setup
* Questions about the IP plan document.
* Questions about firewall set up.
### Remote Hands Request
* Troubleshooting a non-responsive host.
* Re-imaging a host whose OS has become corrupted.
### Configuration Change Request
* Requesting version update for a host OS or virtualization control layer.
* Requests for infrastructure additions.
* If you work with an Account Manager, reach out directly and have them quote prices, kick off the request, and so on.
* If you do not have an Account Manager or have a simple request, you can open a ticket for:
* Firewall upgrades
* Host additions
* Storage LUN expansions
* Additional IP addresses
* Notification on performance issues
Contact MacStadium if any unexplained performance degradation occurs.
MacStadium engineers can troubleshoot and return your infrastructure to optimal performance.
### Monitoring Alerts
* Network Management System (NMS) alerts generated by our operational monitoring system.
* Email alerts generated by internal monitoring sent to [support@macstadium.com](mailto:support@macstadium.com) via an email address associated with the account.
## Subscribe
[status.macstadium.com](http://status.macstadium.com/)
Shows current status of each data center and is the ideal place to stay up-to-date on scheduled maintenance or unplanned outages.
# Compatibility: Performance Improving Features
Source: https://docs.macstadium.com/orka/compatibility/compatibility-performance-improving-features
Orka performance features: saved state, GPU passthrough, I/O boost, and network boost. Intel vs. Apple silicon with macOS version requirements.
## Compatibility based on Apple hardware
| Feature | Intel | Apple silicon |
| ----------------------------------- | ----- | ------------- |
| Use saved state (optimizes startup) | ✅ | ❌ |
| GPU passthrough | ✅ | ✅\* |
| I/O boost\* | ✅ | ✅\* |
| Network boost\* | ✅ | ✅\* |
* GPU passthrough, I/O boost, and Network boost are always enabled for Apple silicon-based nodes and VMs. You cannot manually disable or override these settings on the VM config or VM level.
## (Apple silicon-only) Compatibility based on macOS version
| macOS version | Notes |
| ------------------ | ------------------------------------------------------------------ |
| macOS 13 (Ventura) | Supported |
| macOS 14 (Sonoma) | Supported |
| macOS 15 (Sequoia) | Supported (since Orka 3.2) |
| macOS 26 (Tahoe) | Supported as guest OS (since Orka 3.5; requires Sequoia 15.5 host) |
GPU passthrough, I/O boost, and Network boost are always enabled for Apple silicon VMs. These settings cannot be disabled or overridden at the VM config or VM level.
## (Intel-only) Compatibility based on macOS version
| macOS version | I/O boost | Network boost | GPU passthrough |
| ------------------ | --------- | ------------- | --------------- |
| macOS 13 (Ventura) | ✅ | ✅ | ✅\* |
| macOS 14 (Sonoma) | ✅ | ✅ | ✅\* |
* By default, GPU passthrough is disabled for VM configurations and VMs. When you enable GPU passthrough for an Intel VM, this automatically disables VNC for the VM. Make sure that you will be able to access the VM by SSH or Apple Screen Sharing before enabling GPU passthrough.
# Feature Parity: Apple Hardware
Source: https://docs.macstadium.com/orka/compatibility/feature-parity-apple-hardware
Compatibility across Intel and Apple silicon Orka nodes: supported macOS versions, VM operations, image types, networking, and CI/CD integration support.
Compatibility between Orka features and Intel- and Apple silicon-based nodes, VMs, and images.
## macOS versions
| macOS version | Intel | Apple silicon |
| ------------------ | ----- | ---------------------------------------------------------- |
| macOS 13 (Ventura) | ✅ | ✅ |
| macOS 14 (Sonoma) | ✅ | ✅ |
| macOS 15 (Sequoia) | ❌ | ✅ (since Orka 3.2) |
| macOS 26 (Tahoe) | ❌ | ✅ (since Orka 3.5, guest only; requires Sequoia 15.5 host) |
## General features
| Feature | Intel | Apple silicon |
| ----------------------------------------- | ----- | ------------- |
| Use API IP to access Orka | ✅ | ✅ |
| Use built-in Orka domain to access Orka | ✅ | ✅ |
| Use external custom domain to access Orka | ✅ | ✅ |
| View output in TABLE format | ✅ | ✅ |
| View output in WIDE format | ✅ | ✅ |
| View output in JSON format | ✅ | ✅ |
## Tool configuration
| Feature | Intel | Apple silicon |
| ------------------------------------------------------------ | ----- | ------------- |
| Configure API IP | ✅ | ✅ |
| Configure built-in Orka domain | ✅ | ✅ |
| Configure external custom domain | ✅ | ✅ |
| Upload TLS certificate to use with an external custom domain | ✅ | ✅ |
## Cluster configuration and features
| Feature | Intel | Apple silicon |
| -------------------------------------------------------------- | ----- | ------------- |
| VM scheduling | ✅ | ✅ |
| GPU passthrough | ✅\* | ✅\*\* |
| VM Internet isolation | ✅ | ✅ |
| VM network isolation | ✅ | ✅ |
| Namespaces | ✅ | ✅ |
| Namespaces with custom pods allowed (formerly, sandboxed mode) | ✅ | ✅ |
| Nested virtualization (Beta) | ✅ | ❌ |
The listed configurations are disabled by default and are available upon request.
\*\* GPU passthrough is always enabled by default on Apple silicon-based nodes.
## Checks
| Feature | Intel | Apple silicon |
| ------------------------------ | ----- | ------------- |
| Check the current tool version | ✅ | ✅ |
## Users
| Feature | Intel | Apple silicon |
| --------------------------------- | ----- | ------------- |
| Log in | ✅ | ✅ |
| Log out | ✅ | ✅ |
| Get token | ✅ | ✅ |
| Set token | ✅ | ✅ |
| Manage role bindings for the user | ✅ | ✅ |
## Service accounts
| Feature | Intel | Apple silicon |
| -------------------------------------------- | ----- | ------------- |
| Create service account | ✅ | ✅ |
| Get service account token | ✅ | ✅ |
| List service accounts | ✅ | ✅ |
| Delete service account | ✅ | ✅ |
| Manage role bindings for the service account | ✅ | ✅ |
## Namespaces
| Feature | Intel | Apple silicon |
| -------------------------------------- | ----- | ------------- |
| List namespaces | ✅ | ✅ |
| Create namespace | ✅ | ✅ |
| Delete namespace | ✅ | ✅ |
| Manage role bindings for the namespace | ✅ | ✅ |
## Nodes
| Feature | Intel | Apple silicon |
| -------------------------------------------------------------------------- | ----- | ------------- |
| List nodes | ✅ | ✅ |
| Assign node to a namespace (formerly, grouping) | ✅ | ✅ |
| Assign node to a namespace with enabled custom pods (formerly, sandboxing) | ✅ | ✅ |
| Apply tag (node affinity) | ✅ | ✅ |
| Remove tag (node affinity) | ✅ | ✅ |
## VMs: Listing and info
| Feature | Intel | Apple silicon |
| ------------------------------------------------------------------- | ----- | ------------- |
| List all users' VMs | ✅ | ✅ |
| List specific VMs | ✅ | ✅ |
| List all users' VM configurations | ✅ | ✅ |
| List specific VM configurations | ✅ | ✅ |
| List the VM's ports reserved for VNC, SSH, and Apple Screen Sharing | ✅ | ✅ |
| List the VM's ports reserved for port forwarding | ✅ | ✅ |
## VMs: Create VM configurations
| Feature | Intel | Apple silicon |
| --------------------------------------------------------------------- | ----- | ------------- |
| Create basic VM configuration (name,image) | ✅ | ✅ |
| Create VM configuration with custom memory | ✅ | ✅ |
| Create VM configuration with attached ISO | ✅ | ❌ |
| Create VM configuration with enabled/disabled VNC | ✅ | ✅ |
| Create VM configuration with enabled/disabled I/O boost\* | ✅ | ❌\* |
| Create VM configuration with enabled/disabled Network boost setting\* | ✅ | ❌\* |
| Create VM configuration with enabled/disabled GPU passthrough\* | ✅ | ❌\* |
| Create VM configuration with custom serial number | ✅ | ❌ |
| Create VM configuration with preferred tag (node affinity) | ✅ | ✅ |
| Create VM configuration with required tag (node affinity) | ✅ | ✅ |
| Create VM configuration with custom scheduler | ✅ | ✅ |
* GPU passthrough, I/O boost, and Network boost are always enabled for Apple silicon-based nodes and VMs. You cannot manually disable or override these settings on the VM config or VM level.
## VMs: Deploy VMs
| Feature | Intel | Apple silicon |
| ----------------------------------------------------------------- | ----- | ------------- |
| Deploy basic VM (image) | ✅ | ✅ |
| Deploy VM with custom memory | ✅ | ✅ |
| Deploy VM with attached ISO | ✅ | ❌ |
| Deploy VM with enabled/disabled VNC | ✅ | ✅ |
| Deploy VM with enabled/disabled I/O boost\* | ✅ | ❌\* |
| Deploy VM with enabled/disabled Network boost\* | ✅ | ❌\* |
| Deploy VM with enabled/disabled GPU passthrough\* | ✅ | ❌\* |
| Deploy VM with custom serial number | ✅ | ❌ |
| Deploy VM with preferred tag (node affinity) | ✅ | ✅ |
| Deploy VM with required tag (node affinity) | ✅ | ✅ |
| Deploy VM with custom scheduler | ✅ | ✅ |
| Deploy without VM configuration | ✅ | ✅ |
| Deploy VM from VM configuration | ✅ | ✅ |
| Deploy VM from VM configuration and override the VM configuration | ✅ | ✅ |
* GPU passthrough, I/O boost, and Network boost are always enabled for Apple silicon-based nodes and VMs. You cannot manually disable or override these settings on the VM config or VM level.
## VMs: Start/stop/suspend/resume
| Feature | Intel | Apple silicon |
| --------------------------- | ----- | ------------- |
| Stop VM by name (power off) | ✅ | ❌ |
| Start VM by name (power on) | ✅ | ❌ |
| Suspend VM by name (sleep) | ✅ | ❌ |
| Resume VM by name (wake) | ✅ | ❌ |
## VMs: Delete
| Feature | Intel | Apple silicon |
| ----------------- | ----- | ------------- |
| Delete VM by name | ✅ | ✅ |
## VMs: Storage
| Feature | Intel | Apple silicon |
| ----------------- | ----- | ------------- |
| Shared VM storage | ✅ | ✅ |
| I/O boost\* | ✅ | ✅ \* |
* I/O boost is always enabled on Apple silicon-based nodes and VMs. You cannot manually disable or override it on the VM config or VM level.
### macOS and shared VM storage
| macOS version | Intel | Apple silicon |
| ------------------ | ----- | ------------------ |
| macOS 13 (Ventura) | ✅ | ✅ |
| macOS 14 (Sonoma) | ✅ | ✅ |
| macOS 15 (Sequoia) | ❌ | ✅ (since Orka 3.2) |
| macOS 26 (Tahoe) | ❌ | ✅ (since Orka 3.5) |
## VMs: Networking
| Feature | Intel | Apple silicon |
| -------------------- | ----- | ------------- |
| VNC | ✅ | ✅ |
| SSH | ✅ | ✅ |
| Apple Screen Sharing | ✅ | ✅ |
| Port forwarding | ✅ | ✅ |
| Network boost\* | ✅ | ✅\* |
* Network boost is always enabled on Apple silicon-based nodes and VMs. You cannot manually disable or override it on the VM config or VM level.
## VMs: Performance
| Feature | Intel | Apple silicon |
| --------------- | ----- | ------------- |
| GPU passthrough | ✅ | ❌ |
| I/O boost\* | ✅ | ✅\* |
| Network boost\* | ✅ | ✅\* |
* I/O boost and Network boost are always enabled for Apple silicon-based nodes and VMs. You cannot manually disable or override these settings on the VM config or VM level.
## Images
| Feature | Intel | Apple silicon |
| ------------------------------------------------------------------------------------------------------------------- | ----- | ------------- |
| Deploy from public OCI-compatible images | ✅ | ✅ |
| Deploy from private OCI-compatible images (with registry credentials configured locally) | ✅ | ✅ |
| Push an image from a running VM to an OCI-compatible registry (with registry credentials configured locally) | ✅ | ✅ |
| List images locally stored in the cluster | ✅ | ✅ |
| List remote images | ✅ | ✅ |
| Pull a remote image | ✅ | ✅ |
| Pull a remote image and rename it | ✅ | ✅ |
| Download an image on your local machine | ✅ | ❌ |
| Upload an image from your local machine | ✅ | ❌ |
| Generate a new empty image | ✅ | ❌ |
| Set an image description | ✅ | ✅ |
| Copy and rename an image | ✅ | ✅ |
| Save a new image from the specified VM (Save as) | ✅ | ✅ |
| Overwrite the existing image with its current state from the specified VM (Save) | ✅ | ✅ |
| Resize the disk and automatically resize the partition of the specified VM | ✅ | ✅ |
| Resize the disk and automatically resize the partition of a specified VM and automatically save a new image from it | ✅ | ✅ |
| Only resize the disk of the specified VM | ✅ | ✅ |
| Delete an image | ✅ | ✅ |
## ISOs
| Feature | Intel | Apple silicon |
| ------------------------------- | ----- | ------------- |
| List ISOs | ✅ | ❌ |
| List remote ISOs | ✅ | ❌ |
| Pull a remote ISO | ✅ | ❌ |
| Pull a remote ISO and rename it | ✅ | ❌ |
| Rename an ISO | ✅ | ❌ |
| Copy and rename an ISO | ✅ | ❌ |
| Delete an ISO | ✅ | ❌ |
| Download an ISO | ✅ | ❌ |
| Upload an ISO | ✅ | ❌ |
# Feature Parity: Orka Tools
Source: https://docs.macstadium.com/orka/compatibility/feature-parity-orka-tools
Feature parity matrix: which operations Orka3 CLI, Orka3 API, and Web UI support for VMs, images, nodes, namespaces, and authentication.
## General features
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ----------------------------------------- | --------- | --------- | ------ |
| Use API IP to access Orka | ✅ | ✅ | ✅ |
| Use built-in Orka domain to access Orka | ✅ | ✅ | ✅ |
| Use external custom domain to access Orka | ✅ | ✅ | ✅ |
| View output in TABLE format | ✅ | ❌ | ❌ |
| View output in WIDE format | ✅ | ❌ | ❌ |
| View output in JSON format | ✅ | ✅ | ❌ |
## Tool configuration
| Feature | Orka3 CLI | Orka 3 API | Web UI |
| ------------------------------------------------------------ | --------- | ---------- | ------ |
| Configure API IP | ✅ | ✅ | ✅ |
| Configure built-in Orka domain | ✅ | ✅\* | ✅\* |
| Configure external custom domain | ✅ | ✅\* | ✅\* |
| Upload TLS certificate to use with an external custom domain | ❌ | ✅ | ❌ |
* Requires additional configuration. See [Built-In Orka Domains](/orka/networking-with-orka-at-macstadium/built-in-orka-domains) and [External Custom Domains](/orka/networking-with-orka-at-macstadium/external-custom-domains).
## Checks
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ------------------------------ | --------- | --------- | ------ |
| Check the current tool version | ✅ | ❌ | ✅ |
## Users
| Feature | Orka 3 CLI | Orka3 API | Web UI |
| -------------------------------------------------- | ---------- | --------- | ------ |
| Log in | ✅ | ❌ | ✅\* |
| Log out | ✅ | ❌ | ✅ |
| Get token | ✅ | ❌ | ❌ |
| Set token (authenticate with a pre-existing token) | ✅ | ✅ | ✅ |
| Manage role bindings for the user | ✅ | ✅ | ❌ |
* You need an authentication token obtained with the Orka3 CLI.
## Service accounts
| Feature | Orka3 CLI | Orka3 API | Web UI |
| -------------------------------------------- | --------- | --------- | ------ |
| Create service account | ✅ | ✅ | ❌ |
| Get service account token | ✅ | ✅ | ❌ |
| List service accounts | ✅ | ✅ | ❌ |
| Delete service account | ✅ | ✅ | ❌ |
| Manage role bindings for the service account | ✅ | ✅ | ❌ |
## Namespaces
| Feature | Orka3 CLI | Orka3 API | Web UI |
| -------------------------------------- | --------- | --------- | ------ |
| List namespaces | ✅ | ✅ | ❌ |
| Create namespace | ✅ | ✅ | ❌ |
| Delete namespace | ✅ | ✅ | ❌ |
| Manage role bindings for the namespace | ✅ | ✅ | ❌ |
## Nodes
| Feature | CLI: direct | API | Web UI |
| -------------------------------------------------------------------------- | ----------- | --- | ------ |
| List nodes | ✅ | ✅ | ✅ |
| Assign node to a namespace (formerly, grouping) | ✅ | ✅ | ❌ |
| Assign node to a namespace with enabled custom pods (formerly, sandboxing) | ✅ | ✅ | ❌ |
| Apply tag (node affinity) | ✅ | ✅ | ❌ |
| Remove tag (node affinity) | ✅ | ✅ | ❌ |
## VMs: Listing and info
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ------------------------------------------------------------------- | --------- | --------- | ------ |
| List all users' VMs | ✅ | ✅ | ✅ |
| List specific VMs | ✅ | ✅ | ❌ |
| List all users' VM configurations | ✅ | ✅ | ✅ |
| List specific VM configurations | ✅ | ✅ | ❌ |
| List the VM's ports reserved for VNC, SSH, and Apple Screen Sharing | ✅ | ✅ | ✅ |
| List the VM's ports reserved for port forwarding | ✅ | ✅ | ✅ |
## VMs: Create VM configurations
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ------------------------------------------------------------------- | --------- | --------- | ------ |
| Create basic VM configuration (name, image) | ✅ | ✅ | ✅ |
| Create VM configuration with custom memory | ✅ | ✅ | ✅ |
| Create VM configuration with attached ISO | ✅ | ✅ | ❌ |
| Create VM configuration with enabled/disabled VNC | ✅ | ✅ | ✅ |
| Create VM configuration with enabled/disabled I/O boost | ✅ | ✅ | ✅ |
| Create VM configuration with enabled/disabled Network boost setting | ✅ | ✅ | ✅ |
| Create VM configuration with enabled/disabled GPU passthrough | ✅ | ✅ | ❌ |
| Create VM configuration with custom serial number | ✅ | ✅ | ❌ |
| Create VM configuration with preferred tag (node affinity) | ✅ | ✅ | ❌ |
| Create VM configuration with required tag (node affinity) | ✅ | ✅ | ❌ |
| Create VM configuration with custom scheduler | ✅ | ✅ | ❌ |
## VMs: Deploy VMs
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ----------------------------------------------------------------- | --------- | --------- | ------ |
| Deploy basic VM (name, image) | ✅ | ✅ | ✅ |
| Deploy VM with custom memory | ✅ | ✅ | ✅ |
| Deploy VM with attached ISO | ✅ | ✅ | ❌ |
| Deploy VM with enabled/disabled VNC | ✅ | ✅ | ✅ |
| Deploy VM with enabled/disabled I/O boost | ✅ | ✅ | ✅ |
| Deploy VM with enabled/disabled Network boost | ✅ | ✅ | ✅ |
| Deploy VM with enabled/disabled GPU passthrough | ✅ | ✅ | ❌ |
| Deploy VM with custom serial number | ✅ | ✅ | ❌ |
| Deploy VM with preferred tag (node affinity) | ✅ | ✅ | ❌ |
| Deploy VM with required tag (node affinity) | ✅ | ✅ | ❌ |
| Deploy VM with custom scheduler | ✅ | ✅ | ❌ |
| Deploy without VM configuration | ✅ | ✅ | ❌ |
| Deploy from VM configuration | ✅ | ✅ | ✅ |
| Deploy VM from VM configuration and override the VM configuration | ✅ | ✅ | ❌ |
## VMs: Start/stop/suspend/resume
| Feature | Orka3 CLI | Orka3 API | Web UI |
| --------------------------- | --------- | --------- | ------ |
| Stop VM by name (power off) | ✅ | ✅ | ❌ |
| Start VM by name (power on) | ✅ | ✅ | ❌ |
| Suspend VM by name (sleep) | ✅ | ✅ | ❌ |
| Resume VM by name (wake) | ✅ | ✅ | ❌ |
## VMs: Delete and purge
| Feature | Orka3 CLI | Orka3 API | Web UI |
| -------------------------------------------------------- | --------- | --------- | ------ |
| Delete VM by name | ✅ | ✅ | ✅ |
| Purge VM config (delete the VM config and any instances) | ❌ | ❌ | ✅ |
## VMs: Storage
| Feature | Orka3 CLI | API | Web UI |
| --------------------- | --------- | --- | ------ |
| Shared VM storage\*\* | ❌ | ❌ | ❌ |
| I/O boost | ✅ | ✅ | ✅ |
\*\* You can access and manage the shared storage from within the VM.
## VMs: Networking
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ---------------------- | --------- | --------- | ------ |
| VNC | ✅ | ✅ | ✅ |
| SSH\* | ❌ | ❌ | ❌ |
| Apple Screen Sharing\* | ❌ | ❌ | ❌ |
| Port forwarding | ✅ | ✅ | ❌\*\* |
| Network boost | ✅ | ✅ | ✅ |
* Orka assigns an SSH and an Apple Screen Sharing port to all VMs during deployment. You can view the port information in the Orka CLI, Orka API, and the Orka Web UI. However, you need to manage SSH and Apple Screen Sharing from within the VM.\
\*\* You can see which ports are reserved for port forwarding.
## VMs: Performance
| Feature | Orka3 CLI | Orka3 API | Web UI |
| --------------- | --------- | --------- | ------ |
| GPU passthrough | ✅ | ✅ | ✅ |
| I/O boost\* | ✅ | ✅ | ✅ |
| Network boost\* | ✅ | ✅ | ✅ |
* You cannot save or delete a saved state, or check if a VM configuration is using a saved state. However, if a VM configuration uses a saved state, any VMs deployed with the Orka Web UI (after applying the state to the configuration) will use the saved state.
## Images
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ------------------------------------------------------------------------------------------------------------------- | --------- | --------- | ------ |
| Deploy from public OCI-compatible images | ✅ | ✅ | ✅\* |
| Deploy from private OCI-compatible images (with registry credentials configured locally) | ✅ | ✅ | ✅\* |
| Push an image from a running VM to an OCI-compatible registry (with registry credentials configured locally) | ✅ | ✅ | ❌ |
| List images | ✅ | ✅ | ✅ |
| List remote images | ✅ | ✅ | ✅ |
| Pull a remote image | ✅ | ✅ | ✅ |
| Pull a remote image and rename it | ✅ | ✅ | ✅ |
| Download an image on your local machine | ❌ | ✅ | ❌ |
| Upload an image from your local machine | ❌ | ✅ | ❌ |
| Generate a new empty image | ✅ | ✅ | ✅ |
| Set an image description | ✅ | ✅ | ❌ |
| Copy and rename an image | ✅ | ✅ | ✅ |
| Save a new image from the specified VM (Save as) | ✅ | ✅ | ✅ |
| Overwrite the existing image with its current state from the specified VM (Save) | ✅ | ✅ | ✅ |
| Resize the disk and automatically resize the partition of the specified VM | ✅ | ✅ | ❌ |
| Resize the disk and automatically resize the partition of a specified VM and automatically save a new image from it | ✅ | ✅ | ❌ |
| Only resize the disk of the specified VM | ✅ | ✅ | ❌ |
| Delete an image | ✅ | ✅ | ✅ |
* If the respective VM configuration was created with the Orka3 CLI or the Orka3 API, and if the respective registry credentials are configured for the `orka-default` namespace.
## ISOs
| Feature | Orka3 CLI | Orka3 API | Web UI |
| ------------------------------- | --------- | --------- | ------ |
| List ISOs | ✅ | ✅ | ✅ |
| List remote ISOs | ✅ | ✅ | ✅ |
| Pull a remote ISO | ✅ | ✅ | ✅ |
| Pull a remote ISO and rename it | ✅ | ✅ | ✅ |
| Rename an ISO | ✅ | ✅ | ✅ |
| Copy and rename an ISO | ✅ | ✅ | ✅ |
| Delete an ISO | ✅ | ✅ | ✅ |
| Download an ISO | ❌ | ✅ | ❌ |
| Upload an ISO | ❌ | ✅ | ❌ |
# K8s Native: Orka3 CRD Reference
Source: https://docs.macstadium.com/orka/kubernetes-native/k8s-native-orka3-crd-reference
Field reference for Orka3 Kubernetes custom resource definitions: VirtualMachineConfig and VirtualMachineInstance spec fields, types, and YAML examples.
The recommended way to work with Orka resources is via the Orka3 CLI, Orka3 API, or the Orka Web UI. You can still use `kubectl` instead, but exercise caution and consider managing only VMs and VM configs via YAML. Working with images, ISOs, or nodes directly via YAML requires both advanced Orka3 CRD and Kubernetes knowledge, and might result in unexpected issues.
## virtualmachineconfigs.orka.macstadium.com
### Definitions
| Field | Type | Description |
| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spec` > `cpu` | `integer` | The number of CPU cores to allocate to `VirtualMachineInstances` created from the `VirtualMachineConfig`. |
| `spec` > `gpuPassthrough` | `boolean` | Boolean setting if GPU passthrough is enabled. When enabled, `VncConsole` must be disabled. |
| `spec` > `image` | `string` | The name of the Image to use for the `VirtualMachineInstances` created from the `VirtualMachineConfig`. |
| `spec` > `iso` | `string` | (Intel-only) Attaches the specified ISO (by name) to let you install macOS from scratch on a `VirtualMachineInstance` created from the `VirtualMachineConfig`. When specified, make sure that the `Image` field uses an empty disk generated with the respective operation. |
| `spec` > `memory` | `number` | Memory in GiB. Rounded to the nearest 0.1 GiB. If not specified, will be automatically calculated based on the number of CPU cores. |
| `spec` > `netBoost` | `boolean` | Boolean setting if Network boost is enabled for `VirtualMachineInstances` created from the `VirtualMachineConfig`. |
| `spec` > `nodeName` | `string` | The name of the node where you want the `VirtualMachineInstance` to run. If not specified, the `VirtualMachineInstance` will run on the first available node that matches the criteria (e.g., available CPU and memory, tags, groups, etc.) |
| `spec` > `scheduler` | `string` | The scheduler to use for the deployment of `VirtualMachineInstances` created from the `VirtualMachineConfig`. One of `default`, `most-allocated`. When set to `most-allocated`, `VirtualMachineInstances` are scheduled to `OrkaNodes` having most of their resources allocated. The default setting keeps used vs free resources balanced between `OrkaNodes`. |
| `spec` > `systemSerial` | `string` | A custom serial number for the `VirtualMachineInstances` created from the `VirtualMachineConfig`. The provided serial number must be a valid Mac serial number. |
| `spec` > `tag` | `string` | When specified, `VirtualMachineInstances` created from the `VirtualMachineConfig` will be scheduled for deployment on `OrkaNodes` labeled with the same `Tag`. |
| `spec` > `tagRequired` | `boolean` | Boolean setting if the `Tag` is required. When `true`, `VirtualMachineInstances` will be deployed only on nodes matching the specified `Tag`. |
| `spec` > `vncConsole` | `boolean` | Boolean setting if the VNC console is enabled for `VirtualMachineInstances` created from the `VirtualMachineConfig`. When enabled, `GPUPassthrough` must be disabled. |
### Examples
Create simple VM config
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: VirtualMachineConfig
metadata:
name: my-orka-vm
namespace: orka-default
spec:
cpu: 3
image: sonoma-90gb-orka3-arm
```
Create VM config with attached ISO
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: VirtualMachineConfig
metadata:
name: my-orka-vm
namespace: orka-default
spec:
cpu: 4
image: empty-90gb-orka3-amd
iso: sonoma.iso
```
## virtualmachineinstances.orka.macstadium.com
### Definitions
| Field | Type | Description |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spec` > `cpu` | `integer` | The number of CPU cores to allocate to `VirtualMachineInstance`. |
| `spec` > `customVMMetadata` | `object` | Custom metadata to be passed to the `VirtualMachineInstance`. |
| `spec` > `gpuPassthrough` | `boolean` | Boolean setting if GPU passthrough is enabled. When enabled, `VncConsole` must be disabled. |
| `spec` > `image` | `string` | The name of the Image to use for the `VirtualMachineInstance`. |
| `spec` > `iso` | `string` | (Intel-only) Attaches the specified ISO (by name) to let you install macOS from scratch. When specified, make sure that the `Image` field uses an empty disk generated with the respective operation. |
| `spec` > `memory` | `number` | Memory in GiB. Rounded to the nearest 0.1 GiB. If not specified, the `VirtualMachineInstance` will use the default memory value set in the Orka configuration or will be automatically calculated based on the number of CPU cores. |
| `spec` > `netBoost` | `boolean` | Boolean setting if Network boost is enabled. |
| `spec` > `nodeName` | `string` | The name of the node where you want the `VirtualMachineInstance` to run. If not specified, the `VirtualMachineInstance` will run on the first available node that matches the criteria (e.g., available CPU and memory, tags, etc.) |
| `spec` > `reservedPorts` | `string` | A custom port pairing to enable traffic forwarding. Must be provided in the `:` format (e.g., `1337:3000`). |
| `spec` > `scheduler` | `string` | The scheduler to use for the deployment. One of `default`, `most-allocated`. |
When set to `most-allocated`, `VirtualMachineInstances` are scheduled to `OrkaNodes` having most of their resources allocated. The default setting keeps used vs free resources balanced between `OrkaNodes`.\
`spec` > `systemSerial` | `string` | A custom serial number for the `VirtualMachineInstance`. The provided serial number must be a valid Mac serial number.\
`spec` > `tag` | `string` | When specified, the `VirtualMachineInstance` will be scheduled for deployment on `OrkaNodes` labeled with the same `Tag`.\
`spec` > `tagRequired` | `boolean` | Boolean setting if the `Tag` is required. When `true`, `VirtualMachineInstances` will be deployed only on nodes matching the specified `Tag`.\
`spec` > `vncConsole` | `boolean` | Boolean setting if the VNC console is enabled for `VirtualMachineInstances` created from the `VirtualMachineConfig`. When enabled, `GPUPassthrough` must be disabled.\
`status`>`errorMessage` | `string` | The error message if the deployment failed.\
`status` > `hostIP` | `string` | The IP of the `OrkaNode` on which the `VirtualMachineInstance` is running.\
`status` > `memory` | `string` | The amount of memory allocated to the `VirtualMachineInstance`.\
`status` > `nodeName` | `string` | The name of the `OrkaNode` on which the `VirtualMachineInstance` is running.\
`status` > `phase` | `string` | The state of the `VirtualMachineInstance` deployment.\
`status` > `portWarnings` | `string` | Any port warnings that have occurred during the deployment.\
`status` > `screenSharePort` | `integer` | The Screen Sharing port assigned to the `VirtualMachineInstance`.\
`status` > `sshPort` | `integer` | The SSH port assigned to the `VirtualMachineInstance`.\
`status` > `vncPort` | `integer` | The VNC port assigned to the `VirtualMachineInstance`.
### Examples
**Deploy basic VM**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: VirtualMachineInstance
metadata:
name: my-orka-vm
spec:
image: ghcr.io/macstadium/orka-images/sonoma:latest
```
**Deploy complex VM**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: VirtualMachineInstance
metadata:
name: my-advanced-orka-vm
spec:
cpu: 4
gpuPassthrough: false
image: sonoma-90gb-orka3-arm
netBoost: true
scheduler: default-scheduler
vncConsole: true
tag: my-tag
tagRequired: false
```
## images.orka.macstadium.com
### Definitions
| Field | Type | Description |
| --------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spec` > `checksum` | `string` | (amd64-only) The automatically calculated MD5 checksum of the image file represented by the Image. Orka populates Checksum only after you explicitly request the checksum. |
| `spec` > `destination` | `string` | A new name for the Image resulting from the Image save operation. Leave empty for commit operations. |
| `spec` > `owner` | `string` | The user who initially created the image file represented y the Image. |
| `spec` > `size` | `string` or `integer` | The size of the image file in formatted bytes. |
| `spec` > `source` | `string` | The name of an `Image`, `RemoteImage` or `VirtualMachineInstance` to use as a source for a specific Image operation. Must match the `SourceType`. |
| `spec` > `sourceNamespace` | `string` | The namespace of the source VM (for commit and save). Uses `orka-default` if not specified. |
| `spec` > `sourceType` | `string` | Modifier used for Image operations. One of `generated` (for generate), `local` (for copy), `remote` (for pull), `vm` (for commit and save). |
| `status` > `errorMessage` | `string` | The error message from the last failed operation with this `Image`. |
| `status` > `lastUpdatedTimestamp` | `string` | The timestamp for the last `Image` update (in the ISO 8601 format). |
| `status` > `state` | `string` | The current state of the image. One of `Ready`, `Updating`, `Failed`. |
### Examples
**Existing Apple silicon-based image**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Image
metadata:
annotations:
orka.macstadium.com/description: sonoma-90gb-orka3-arm
creationTimestamp: "2023-10-16T09:55:25Z"
generation: 1
labels:
kubernetes.io/arch: arm64
name: sonoma-90gb-orka3-arm
namespace: orka-default
resourceVersion: "3064"
uid: f42805a1-7c71-4eaa-b61a-6206b59c0e97
spec:
size: 90G
status:
lastUpdatedTimestamp: "2023-10-16T09:55:25Z"
state: Ready
```
**Existing Intel-based image**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Image
metadata:
annotations:
orka.macstadium.com/description: 90GBVenturaSSH.img
creationTimestamp: "2023-10-16T09:55:25Z"
generation: 1
labels:
kubernetes.io/arch: amd64
name: 90gbventurassh.img
namespace: orka-default
resourceVersion: "3032"
uid: e329b4e4-90e5-4b3c-9c2c-8651923d87ed
spec:
size: 90G
status:
lastUpdatedTimestamp: "2023-10-16T09:55:25Z"
state: Ready
```
**Generate empty image**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Image
metadata:
name: empty-90gb-orka3-amd
namespace: orka-default
spec:
size: 90G
sourceType: generated
```
**Copy local image**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Image
metadata:
name: copy-sonoma-90gb-orka3-arm
namespace: orka-default
spec:
sourceType: local
source: sonoma-90gb-orka3-arm
```
**Pull remote image**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Image
metadata:
name: pulled-ventura-orka3-arm
namespace: orka-default
spec:
sourceType: remote
source: 90gbventurassh.orkasi
```
## isos.orka.macstadium.com
### Definitions
| Field | Type | Description |
| --------------------------------- | --------------------- | ------------------------------------------------------------------------------------ |
| `spec` > `size` | `string` or `integer` | The size of the ISO file in formatted bytes. |
| `spec` > `source` | `string` | The name of an `Iso` or `RemoteIso` to use as a source for a specific Iso operation. |
| `spec` > `sourceType` | `string` | Modifier used for Iso operations. One of `local` (for copy) or `remote` (for pull). |
| `status` > `errorMessage` | `string` | The error message from the last failed operation with this `Iso`. |
| `status` > `lastUpdatedTimestamp` | `string` | The timestamp for the last `Iso` update (in the ISO 8601 format). |
| `status` > `state` | `string` | The current state of the Iso. One of `Ready`, `Updating`, `Failed`. |
### Examples
**Existing ISO**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Iso
metadata:
annotations:
orka.macstadium.com/description: Ventura.iso
creationTimestamp: "2023-10-16T09:55:25Z"
generation: 1
name: ventura.iso
namespace: orka-default
resourceVersion: "3079"
uid: 1c6f8e5c-fc0b-449b-ba03-2351d41d8d34
spec:
size: 2G
status:
lastUpdatedTimestamp: "2023-10-16T09:55:25Z"
state: Ready
```
**Copy local ISO**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Iso
metadata:
name: copy-big-sur.iso
namespace: orka-default
spec:
sourceType: local
source: big-sur.iso
```
**Pull remote ISO**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: Iso
metadata:
name: pulled-ventura.iso
namespace: orka-default
spec:
sourceType: remote
source: ventura.iso
```
## remoteimages.orka.macstadium.com
### Definitions
| Field | Type | Description |
| -------------------- | --------------------- | ------------------------------------------------------ |
| `spec` > `imageName` | `string` | The name of the image file represented by the `Image`. |
| `spec` > `size` | `string` or `integer` | The size of the image file in formatted bytes. |
### Examples
**Existing remote image**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: RemoteImage
metadata:
creationTimestamp: "2023-10-16T09:55:25Z"
generation: 1
labels:
kubernetes.io/arch: amd64
name: 90gbventurassh.img
namespace: orka-default
resourceVersion: "3095"
uid: 29d907bc-e284-487b-8352-8466f89c8568
spec:
imageName: 90GBVenturaSSH.img
size: 90G
```
## remoteisos.orka.macstadium.com
### Definitions
| Field | Type | Description |
| ------------------ | --------------------- | -------------------------------------------------- |
| `spec` > `isoName` | `string` | The name of the ISO file represented by the `Iso`. |
| `spec` > `size` | `string` or `integer` | The size of the ISO file in formatted bytes. |
### Examples
**Existing remote iso**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: RemoteIso
metadata:
creationTimestamp: "2023-10-16T09:55:25Z"
generation: 1
name: ventura.iso
namespace: orka-default
resourceVersion: "3092"
uid: 25de0e37-e99d-4dde-9931-c5d6a872166e
spec:
isoName: Ventura.iso
size: 16G
```
## orkanodes.orka.macstadium.com
### Definitions
| Field | Type | Description |
| ------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `spec` > `namespace` | `string` | The name of a specific namespace to which a node is assigned. Only users with appropriate access to that namespace will have the ability to deploy `VirtualMachineInstances` on that `OrkaNode`. |
| `spec` > `tags` | `array` of `string` items | One or more tags setting node affinity. Node affinity indicates that the tagged `OrkaNode` is preferred for the deployment of `VirtualMachineInstances` with the same tag. |
| `status` > `allocatableCpu` | `integer` | The complete amount of CPU cores on the node when no `VirtualMachineInstances` are deployed. |
| `status` > `allocatableGpu` | `integer` | The complete amount of GPU cores on the node when no `VirtualMachineInstances` are deployed. |
| `status` > `allocatableMemory` | `string` | The complete amount of memory (in GiB) on the node when no `VirtualMachineInstances` are deployed. |
| `status` > `availableCpu` | `integer` | The amount of available CPU on the node. |
| `status` > `availableGpu` | `integer` | The amount of available GPU on the node. |
| `status` > `availableMemory` | `string` | The amount of available Memory on the node. |
| `status` > `nodeIP` | `string` | The IP of the `OrkaNode`. |
| `status` > `nodeType` | `string` | The type of the `OrkaNode`. Usually, `WORKER`. |
| `status` > `phase` | `string` | The status of the OrkaNode. One of `READY`, `NOT READY`. |
### Examples
**Existing node**
```yaml theme={null}
apiVersion: orka.macstadium.com/v1
kind: OrkaNode
metadata:
creationTimestamp: "2023-10-16T09:55:25Z"
generation: 1
labels:
kubernetes.io/arch: amd64
name: mini-25
namespace: orka-default
ownerReferences:
- apiVersion: v1
blockOwnerDeletion: true
controller: true
kind: Node
name: mini-25
uid: 5bde48ba-a951-46c6-814e-6147cca52dca
resourceVersion: "3052"
uid: dade0833-c06e-45ac-86ec-67abba759d96
spec:
namespace: orka-default
tags: []
status:
allocatableCpu: 12
allocatableGpu: 0
allocatableMemory: 62.56G
availableCpu: 12
availableGpu: 0
availableMemory: 62.56G
nodeIP: 10.221.188.35
nodeType: WORKER
phase: READY
```
# Kubernetes-native Orka resource management
Source: https://docs.macstadium.com/orka/kubernetes-native/k8s-native-overview
Manage Orka resources with kubectl. Covers authenticating via orka3 CLI, applying VM configs as YAML, and creating namespaces for custom pod workloads.
Everything you need to tap into the underlying Kubernetes layer of Orka.
Starting with Orka 3.0, all Orka resources are Kubernetes-native. They are [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) with detailed custom resource definitions.
This lets you work with Orka resources straight from `kubectl`, if that's your preferred tool. You can also run custom pods in namespaces, created with the enable custom pods setting.
The recommended way to work with Orka resources is via the Orka3 CLI, Orka3 API, or the Orka Web UI. You can still use `kubectl` instead, but exercise caution and consider managing only VMs and VM configs via YAML. Working with images, ISOs, or nodes directly requires both advanced Orka3 CRD and Kubernetes knowledge, and might result in unexpected issues.
## Workflow
1. Install `kubectl` locally or upgrade your existing installation. For example:
```bash theme={null}
brew install kubectl
# OR
brew upgrade kubectl
```
2. Authenticate with your Orka cluster:
**Orka3 CLI**
```bash theme={null}
orka3 login
# OR
orka3 user set-token
```
3. Manage Orka resources with `kubectl`:
```bash theme={null}
kubectl apply -f --namespace=
# OR
kubectl get --namespace=
# OR
kubectl edit --namespace=
# OR
kubectl delete --namespace=
```
4. Create and configure a namespace for running custom pods.
First, you need to create a namespace with enabled custom pods. Next, you must grant access to the namespace to the users who need to deploy to it. And finally, you need to assign computational resources to the namespace. Note that you will not be able to deploy Orka resources to this namespace.
**Orka3 CLI**
```bash theme={null}
orka3 namespace create --enable-custom-pods
orka3 rb add-subject --user --namespace
orka3 node namespace
```
5. Manage your custom pods with `kubectl`.
```bash theme={null}
kubectl apply -f --namespace=
# OR
kubectl get --namespace=
# OR
kubectl edit --namespace=
# OR
kubectl delete --namespace=
```
For any custom pods you need to run, add the following toleration to the pod:
**YAML**
```json theme={null}
{"key": "orka.macstadium.com/namespace-reserved", "value": ""}
```
## Limitations
* Your access to Orka resources depends on the role of the user you authenticated with. For more information, see [here](/orka/orka-cluster-access/cluster-access-management-overview).
* You can run custom pods only in a namespace created with the enable custom pods setting.
* You cannot run custom pods in the `orka-default` namespace.
* For any custom pods you want to run, you must add the following toleration:
**YAML**
```json theme={null}
{"key": "orka.macstadium.com/namespace-reserved", "value": ""}
```
# Kubernetes persistent volumes in Orka namespaces
Source: https://docs.macstadium.com/orka/kubernetes-native/k8s-native-persistent-volumes
Use Kubernetes persistent volumes in Orka custom pod namespaces. Request a PV from MacStadium, set up kubectl access, create PVCs, and deploy pods.
How to tap into Kubernetes persistent volumes for your Orka environment.
For security reasons, Orka does not let you configure [persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) yourself. The MacStadium team needs to do that for you. However, when a persistent volume is configured for your environment, you can create persistent volume claims and deploy pods that consume the respective persistent volume.
**Quick command summary**
```bash theme={null}
brew install kubectl
orka3 login OR orka3 user set-token
orka3 ns create --enable-custom-pods
orka3 node namespace
orka3 rb add-subject --namespace --user
kubectl apply -f *.yaml --namespace=
kubectl get [pods / pvc]
kubectl describe
kubectl delete
```
## Limitations
Persistent volumes are not applicable to standard Orka VMs. They can be consumed only by pods deployed with `kubectl`, and are called by functions such as `attach-disk`.
If you want to persist the storage of a standard Orka VM, use the VM commit, save, or push operations.
## Step 1: Request a Persistent Volume
Contact the MacStadium team and request a persistent volume (PV) for your Orka environment. Work closely with the team to help them create a PV that matches your requirements. Note that at this step, you need to decide on the name of the namespace where the PV will be created.
## Step 2: Get Kubernetes-Ready
You need to install `kubectl` and configure a namespace with permissions to run custom pods.
1. If not already installed, install `kubectl` locally. For example:
```bash theme={null}
brew install kubectl
```
2. Authenticate with the Orka cluster.
```bash theme={null}
orka3 login
OR
orka user set-token
```
3. Set up the namespace for the PV. The name must match the name confirmed with the MacStadium team when requesting the PV. The namespace must have custom pods enabled. Next, you need to move computational resources to the namespace and you need to grant namespace access to the users or service accounts which will be working with the namespace.
```bash theme={null}
orka3 namespace create --enable-custom-pods
orka3 node namespace
orka3 rb add-subject --namespace --user
```
## Step 3: Create the Persistent Volume Claim
A persistent volume claim (PVC) lets you tap into your persistent volume and consume it. You need to create a basic yaml manifest for the PVC and apply it to the environment.
1. Create the PVC manifest. For more information, see [Kubernetes Documentation: PersistentVolumeClaims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims). For example:
**pvc.yaml**
```yaml theme={null}
# pvc.yaml
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: mypvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 20Gi
```
The values for `metadata.name` and `metadata.namespace` must match the values for `claimRef.name` and `claimRef.namespace` declared in the manifest of the persistent volume. Double-check with the MacStadium team for these values.
2. Apply the PVC. Replace `pvc.yaml` with the complete file path to your own PVC manifest. Replace `` with the namespace you created earlier.
```bash theme={null}
kubectl apply -f pvc.yaml --namespace=
```
3. Verify that the persistent volume claim is bound to the persistent volume.
```bash theme={null}
kubectl get pvc
```
If the persistent volume claim works as expected, you will see a similar output:
![kubectl get pvc output showing PVC bound to persistent volume]()
**Status Pending?** If the status is `Pending` instead of `Bound`, double-check your PVC manifest, fix any naming issues, remove the old PVC with `kubectl delete pvc `, and re-apply the fixed manifest. If the problem persists, contact the MacStadium team.
## Step 4: Deploy a Pod That Uses the Persistent Volume
Now that you have created a PVC and bound it to the PV, you can deploy a pod that uses the PV. Create a pod manifest and apply it.
1. Create the pod manifest. The pod needs to reference both the PV and the PVC. For example:
**mypod.yaml**
```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
name: mypod
spec:
volumes:
- name: my-pv
persistentVolumeClaim:
claimName: mypvc
containers:
- name: mypod
image: ubuntu
command: ["/bin/bash", "-ec", "while :; do echo '.'; sleep 5 ; done"]
volumeMounts:
- mountPath: "/usr/share/mypod"
name: my-pv
restartPolicy: Never
tolerations:
- key: orka.macstadium.com/namespace-reserved
value:
```
This example deploys a Linux VM. Pay attention to the command line and the tolerations section. Without the command line, the state of your Linux VM will become Stopped. Without the tolerations section, you won't be able to create the pod.
2. Apply the pod. Replace `mypod.yaml` with the complete file path to your pod manifest.
```bash theme={null}
kubectl apply -f mypod.yaml --namespace=
```
3. Verify that the pod is deployed and running.
```bash theme={null}
kubectl get pods
```
If the pod works as expected, you will see a similar output:
![kubectl get pods output showing pod running]()
4. Verify that the pod uses the claim and the persistent volume. Look for the data listed for Volumes.
```bash theme={null}
kubectl describe pod
```
## (Optional) Step 5: Deploy a Service to Handle the Networking Between Your Pods and Your Orka VMs
If you want to have connectivity between your Orka VMs and any pods deployed with `kubectl`, you need to deploy a networking service. For more information, see [Kubernetes Documentation: Service](https://kubernetes.io/docs/concepts/services-networking/service/).
Make sure to use the networking information provided in [My Cloud](/macstadium/macstadium-overview/ip-plan) when assigning IPs.
## What's Next: Delete the PVC and Release the PV
When you no longer need to use a PVC and the respective PV, you can delete the PVC to release the PV.
1. Delete the PVC.
```bash theme={null}
kubectl delete pvc
```
2. Contact the MacStadium team.
* If you want to reclaim the storage, an administrator might need to clean it up and verify that it's available for use again. This would depend on the provisioning type and the reclaim policy for the PV.
* If you no longer need the storage, an administrator can remove the PV.
# 1. AWS Side of the VPN Tunnel
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/1-aws-side-of-the-vpn-tunnel
Configure the AWS side of an IPsec site-to-site VPN: create a customer gateway, virtual private gateway, and VPN connection in Amazon VPC.
How to configure the AWS side of your VPN tunnel between AWS and Orka.
**Before you begin:** You need your firewall's public IP (the `FW1-Outside` address), shown at the top of the firewall's section in [My Cloud](/macstadium/macstadium-overview/ip-plan), and the CIDR range for the `Private-1` network (most likely `10.221.188.0/24`), shown in the **Subnet ID** column of the firewall's **IP Allocation** table.
To establish a stable, persistent connection between an Amazon Virtual Private Cloud (Amazon VPC) and your Orka cluster, you need to configure an IPsec site-to-site VPN (VPN tunnel) between the two.
Routing from Amazon to Orka is static.
## Step 1: Log in to your VPC service
1. Log in to your AWS Management Console and access your VPC service. In the top right corner of the screen, make sure that you're working in the correct region.
2. In the **Find Services** bar, type `VPC` and navigate to the service.
![AWS Management Console Find Services bar with VPC typed]()
## Step 2: Create a customer gateway
In Amazon, the [customer gateway](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPC_VPN.html#VPN) represents the Orka end of the tunnel.
1. In the VPC service sidebar, locate the **Virtual Private Network** menu and select **Customer Gateways**.
![AWS VPC sidebar with Customer Gateways selected]()
2. Click **Create Customer Gateway**.
![Create Customer Gateway button in AWS VPC console]()
3. Fill in the form.
1. Provide a **Name**. Set a name that helps you identify the gateway easily.
2. Select **Static** routing.
3. In the **IP Address** text box, provide your firewall's public IP (the `FW1-Outside` address) from My Cloud.
4. Ignore the remaining settings.
![Create Customer Gateway form with name, routing, and IP address fields]()
4. Click **Create Customer Gateway**.
![AWS console confirmation of customer gateway created successfully]()
## Step 3: Set up a virtual private gateway
In Amazon, the [virtual private gateway](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPC_VPN.html#VPN) represents the Amazon end of the tunnel.
1. In the VPC service sidebar, locate the **Virtual Private Network** menu and select **Virtual Private Gateways**.
![AWS VPC sidebar with Virtual Private Gateways selected]()
2. Click **Create Virtual Private Gateway**.
![Create Virtual Private Gateway button in AWS VPC console]()
3. Fill in the form.
1. Provide a **Name tag**. Set a name that helps you identify the gateway easily.
2. Select **Amazon default ASN**
3. Click **Create Virtual Private Gateway**.
![Create Virtual Private Gateway form with name tag and ASN fields]()
4. On the **Virtual Private Gateways** dashboard, right-click the newly created virtual private gateway and select **Attach to VPC**.
![Virtual Private Gateways dashboard with Attach to VPC option in context menu]()
5. Select your VPC from the drop-down menu and click **Yes, Attach**.
![Attach to VPC dialog with VPC dropdown and Yes Attach button]()
Next, you need to manually enable [route propagation](https://docs.aws.amazon.com/vpn/latest/s2svpn/VPNRoutingTypes.html) for the virtual private gateway.
1. In the VPC service sidebar, locate the **Virtual Private Cloud** menu and select **Route Tables**.
![AWS VPC sidebar with Route Tables selected]()
2. In the list of routing tables, select the main route table for your VPC.
3. At the bottom of the screen, select **Route Propagation**. If your virtual private gateway is not listed, make sure that it's attached to the VPC.
4. Click **Edit route propagation**.
![Route Propagation tab showing Edit route propagation button]()
5. Select the **Propagate** checkbox and click **Save**.
## Step 4: Create the tunnel
After you have a customer gateway and a virtual private gateway in place, you can configure the tunnel.
1. In the VPC service sidebar, locate the **Virtual Private Network** menu and select **Site-to-Site VPN Connections**.
![AWS VPC sidebar with Site-to-Site VPN Connections selected]()
2. Click **Create VPN Connection**.
![Create VPN Connection button in AWS VPC console]()
3. Fill in the form.
1. Provide **Name tag**.
2. For **Target Gateway Type**, select **Virtual Private Gateway**, and from the **Virtual Private Gateway** drop-down menu, select the virtual private gateway you created earlier.
3. Select that you want to use an **Existing** customer gateway, and from the **Customer Gateway ID** drop-down menu, select the customer gateway that you created earlier.
4. For **Routing Options**, select **Static**.
5. In **Static IP Prefixes**, provide the [CIDR notation](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation) for your `Private-1` network. Most likely: `10.221.188.0/24`.
6. Ignore the remaining options (not shown on the screenshot).
![Create VPN Connection form with gateway, routing, and CIDR prefix fields]()
4. Click **Create VPN Connection**.
![283f047-create-vpn-success.png]()
## Step 5: Ensure that AWS allows inbound traffic
Based on your requirements and current setup, you might need to enable inbound traffic from Orka to AWS.
See [Amazon VPC Documentation: Security Groups for Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) and [Amazon VPC Documentation: Network ACLs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html).
# 1. GCP Side of the VPN Tunnel
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/1-gcp-side-of-the-vpn-tunnel
Configure the GCP side of an IPsec site-to-site VPN to your Orka cluster: create a Classic VPN gateway and tunnel using policy-based routing with IKEv2.
How to configure the GCP side of your VPN tunnel between GCP and Orka.
**Before you begin:** You need your firewall's public IP (the `FW1-Outside` address), shown at the top of the firewall's section in [My Cloud](/macstadium/macstadium-overview/ip-plan), and the CIDR range for the `Private-1` network (most likely `10.221.188.0/24` or `10.10.10.0/24`), shown in the **Subnet ID** column of the firewall's **IP Allocation** table.
To establish a stable, persistent connection between a Google Cloud Platform (GCP) private cloud and your Orka environment, you need to configure a policy-based IPsec site-to-site VPN between the two clouds.
Currently, you can create only a classic VPN connection with policy-based routing from GCP to Orka. It consists of one tunnel and one interface and does not provide high availability. For more information about this option, see [Google Cloud Documentation: Classic VPN](https://cloud.google.com/vpn/docs/how-to/choosing-a-vpn#classic-vpn).
## Step 1: Log in to GCP
1. Log in to the GCP console with your credentials.
2. In the toolbar at the top, make sure that you're working with the correct project.
![GCP project selector in the toolbar]()
## Step 2: Create the VPN connection
* From the GCP console sidebar, scroll to the *Networking* section and select **Hybrid Connectivity** > **VPN**.
![GCP console Hybrid Connectivity VPN navigation]()
Classic VPN connections in GCP consist of a gateway and tunnel. You can create a gateway and a tunnel at once or you can add a new tunnel to an existing gateway.
## Step 3a: Create gateway and tunnel
If you don't have a classic VPN gateway that you want to use, complete the following steps.
1. If you don't have any VPNs created yet, click **Create VPN connection**.
2. If you have one or more VPNs created, click **+ VPN SETUP WIZARD**.
3. Select **Classic VPN** and click **Continue**.\
The **High-availability (HA) VPN** is currently not supported as an option. For more information about the available options, see [Google Cloud Documentation: Choosing a VPN option](https://cloud.google.com/vpn/docs/how-to/choosing-a-vpn).
4. In the *Google Compute Engine VPN gateway* section, provide **Name** and **Description**.
5. For **Network**, select the GCP network that needs to be able to access Orka.
6. Select **Region**.\
For more information about this setting, see [Google Cloud Documentation: Regions and Zones](https://cloud.google.com/compute/docs/regions-zones).
7. Select or create a reserved IP address for the connection.\
You will need this IP address when you configure the Orka side of the tunnel.
8. In the **Tunnels** section, provide **Name** and **Description**.
9. For **Remote peer IP address**, provide your firewall's public IP (the `FW1-Outside` address) from My Cloud.
10. For **IKE version**, verify that **IKEv2** is selected.
11. Provide or generate an **IKE pre-shared key**.
Keep a record of the pre-shared key. You will need it later.
12. For **Routing options**, select **Policy-based**.
13. For **Remote network IP ranges**, provide the IP range in [CIDR notation](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation) for the `Private-1` network. This is the **Subnet ID** value for `Private-1` in the **IP Allocation** table in My Cloud.
14. (Optional) Select one or more GCP subnetworks to reduce latency between your GCP private cloud and your Orka private cloud.\
For more information, see [Google Cloud Documentation: Networks and subnets](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets).
15. (Optional) Provide one or more IP ranges within your GCP local network that needs to access Orka.
16. Click **Done**.
17. Click **Create**.
After the creation is complete, the VPN tunnel status is: `First handshake`.
#### **Example: Create gateway and tunnel**
This image shows a sample configuration for the VPN gateway and tunnel.
![Sample GCP VPN gateway and tunnel configuration]()
## Step 3b: Add a new tunnel to an existing gateway
If you have an existing classic VPN gateway that you want to use for the connection, complete the following steps.
1. Select **Cloud VPN Tunnels** and click **Create VPN tunnel**.
![Cloud VPN Tunnels tab with Create VPN tunnel button]()
2. Select the VPN gateway that you want to use and click **Continue**.
Make sure that you have selected a classic VPN gateway. High-availability gateways are not supported.
3. Provide **Name**.
4. (Optional) Provide **Description**.
5. For **Remote peer IP address**, provide your firewall's public IP (the `FW1-Outside` address) from My Cloud.
6. For **IKE version**, verify that **IKEv2** is selected.
7. Provide or generate an **IKE pre-shared key**.
Keep a record of the pre-shared key. You will need it later.
8. For **Routing options**, select **Policy-based**.
9. For **Remote network IP ranges**, provide the IP range in [CIDR notation](https://www.digitalocean.com/community/tutorials/understanding-ip-addresses-subnets-and-cidr-notation-for-networking#cidr-notation) for the `Private-1` network. This is the **Subnet ID** value for `Private-1` in the **IP Allocation** table in My Cloud.
10. (Optional) Select one or more GCP subnetworks to reduce latency between your GCP private cloud and your Orka environment.\
For more information, see [Google Cloud Documentation: Networks and subnets](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets).
11. (Optional) Provide one or more IP ranges within your GCP local network that needs to access Orka.
12. Click **Create**.
After the creation is complete, the VPN tunnel status is: `First handshake`.
#### **Example: Create the VPN gateway and tunnel**
This image shows a sample configuration for the VPN connection.
![Sample GCP VPN tunnel configuration for adding to an existing gateway]()
## Step 4: Ensure that the GCP firewall allows ingress traffic
Based on your requirements, you might need to enable ingress traffic from Orka to GCP in the GCP firewall. For more information, see [Google Cloud Documentation: Configuring firewall rules > Example configurations](https://cloud.google.com/vpn/docs/how-to/configuring-firewall-rules#example_configurations).
# 2. AWS VPN Tunnel Configuration File
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file
Download the AWS VPN config file and fill in Orka network values for your Cisco ASAv: outside interface, Private-1 subnet, NAT rules, and VPC details.
Download the VPN configuration file from Amazon and fill it in with your Orka network configuration.
**You need:**
* The name of your firewall's outside interface. By default, this is `Outside`.
* The IP address for the `Private-1` network, from the `Private-1` row of the **IP Allocation** table in [My Cloud](/macstadium/macstadium-overview/ip-plan).
* The subnet mask for the `Private-1` network, from the same **IP Allocation** row.
* The IPv4 address of your Amazon VPC.
* The subnet mask for your Amazon VPC converted from its CIDR notation (i.e. `255.255.0.0` instead of `/16`).
After you [have created your VPN tunnel in Amazon](/orka/networking-with-orka-at-macstadium/1-aws-side-of-the-vpn-tunnel), you need to configure your Cisco firewall to recognize the connection and let traffic into your Orka cluster.
Amazon provides a semi-prefilled configuration file with very detailed instructions. First, you need to download the configuration file and provide the missing information indicated by placeholders. Next, you'll need to [feed the configuration](/orka/networking-with-orka-at-macstadium/3-aws-orka-side-of-the-vpn-tunnel) into your Cisco ASAv to complete the setup.
## Step 1: Download the file from Amazon
1. Verify that you are logged in to your AWS Management Console and you're working in the correct region.
2. [Verify that you have created a tunnel in Amazon.](/orka/networking-with-orka-at-macstadium/1-aws-side-of-the-vpn-tunnel)
3. Navigate to your VPC service. In the VPC service sidebar, locate the **Virtual Private Network** menu and select **Site-to-Site VPN Connections**.
![AWS VPC sidebar with Site-to-Site VPN Connections selected]()
4. In the list, select your newly created VPN connection and click **Download Configuration**.
![AWS VPN connection selected with Download Configuration button visible]()
5. Fill in the form and click **Download**.
1. For **Vendor**, select **Cisco Systems, Inc.**.
2. For **Platform**, select **ASA 5500 Series**.
3. For **Software**, select **ASA 9.x** for a policy-based VPN OR **ASA 9.7 + VTI** for a route-based VPN.
![Download Configuration dialog with Cisco ASA 5500 vendor and platform selected]()
## Step 2: Fill in the configuration file
Unless you have extensive experience with AWS and ASAv configurations, follow the instructions in the configuration file to the letter. Otherwise, your site-to-site VPN might not work as expected.
1. Open the configuration file in a text editor.
2. Replace all placeholders with their respective values.
| Placeholder | Value | Description | More information |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `` | `Outside` | The **name** of the outside interface of your Cisco ASAv device (the `Outside` network). | My Cloud |
| `` | (Sample) `outside_access_in` | Any unique name. This will be the name for the access control list that permits the creation of the tunnel and the traffic over it. | [Cisco Documentation: Cisco Access Control Lists](https://www.cisco.com/c/en/us/support/docs/security/ios-firewall/23602-confaccesslists.html) |
| `` | (Sample) `192.168.0.0` | The IPv4 address of your Amazon VPC (without the subnet mask bit notation). | You can get this value by selecting your VPC in AWS > VPC dashboard and checking the **Details** at the bottom of the screen. |
| `` | (Sample) `255.255.0.0` | The subnet mask for your Amazon VPC, converted from its CIDR notation. | You can get this value by selecting your VPC in AWS > VPC dashboard and checking the **Description** at the bottom of the screen. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the `/16` notation converts to a `255.255.0.0` subnet mask). |
| `` | (Sample) `amzn_vpn_map` | Any unique name for the crypto map. It must not be already in use by any other crypto maps you might have configured. | [Cisco Documentation: Configuring Crypto Maps](https://www.cisco.com/c/en/us/td/docs/security/vpn_modules/6342/vpn_cg/6342site3.html#wp1036915) |
| `` | (Sample) `192.168.0.1` | An IP address in your Amazon VPC that can serve as an SLA monitor keeping the site-to-site tunnel alive. | You can set this to the `` address plus one. |
| `` | `10.221.188.0` | The IP address for the `Private-1` network. | The `Private-1` row of the **IP Allocation** table in My Cloud |
| `` | `255.255.255.0` | The subnet mask for the `Private-1` network. | The `Private-1` row of the **IP Allocation** table in My Cloud |
3. Uncomment the following lines. To uncomment, remove `! `at the start of the line.
* `access-list amzn-filter extended permit ip ...`
* `object`- and `nat`-related configuration at the end of the config file.
4. Keep the following line. This ensures the SLA monitor works as expected.
```
object network obj-SrcNet subnet 0.0.0.0 0.0.0.0
```
Note that based on your network configuration and requirements, you can modify this line to map to the subnet and the subnet mask for the `Private-1` network from the **IP Allocation** table in My Cloud. If you choose to modify this line, **do not** configure the `` value.
5. Change `nat (inside,outside)` to `nat (Private-1,Outside)`.
6. (Optional) Delete the remaining commented lines to clean up the file. Commented lines are indicated by `! `at the beginning of the line.
7. Save your changes.
# 2. GCP VPN Tunnel Configuration File
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/2-gcp-vpn-tunnel-configuration-file
Complete the Cisco ASA/ASAv config template for your GCP-to-Orka VPN tunnel. Fill in GCP network, VPN IP, Orka Private-1 network, and IKEv2 pre-shared key.
**Before you begin:** From [My Cloud](/macstadium/macstadium-overview/ip-plan), you need the `Private-1` IP address and subnet mask, shown in the `Private-1` row of the firewall's **IP Allocation** table. You also need the `Outside` interface name (by default, `Outside`). From GCP, you need your local network's IPv4 address and subnet mask (converted from CIDR notation, e.g. `255.255.0.0` instead of `/16`).
After you [have created your site-to-site VPN connection in Google Cloud Platform (GCP)](/orka/networking-with-orka-at-macstadium/1-gcp-side-of-the-vpn-tunnel), you need to configure your Cisco firewall to recognize the connection and let traffic into your Orka environment.
You can use the configuration template provided below and fill in the missing information. You need to provide data from both GCP and Orka.
## Configuration template
Unless you have extensive experience with GCP and ASA/ASAv configurations, use the configuration from the template. Otherwise, your site-to-site VPN might not work as expected.
```
! #1: Placeholders
!
! { gcp_network_address } - The address of the GCP local network that needs to have access to Orka.
! { gcp_network_mask } - The subnet mask of the GCP local network that needs to have access to Orka.
! { gcp_vpn_ip } - The public IP address of the cloud VPN gateway in GCP.
! { macstadium_network_name } - The name of the private network in Orka that needs to be accessed by GCP. By default, this is Private-1.
! { macstadium_network_address } - The IP address of the private network in Orka that needs to be accessed by GCP. By default, this is Private-1.
! { macstadium_network_mask } - The subnet mask of the private network in Orka that needs to be accessed by GCP. By default, this is Private-1.
! { macstadium_public_ip } - The IP address of the public network of your Orka private cloud. By default, this is FW1-Outside.
! { macstadium_outside_interface } - The name of the outside interface of your Cisco ASA/ASAv device. By default, this is Outside.
! { shared_key } - The IPSec pre-shared key used when creating the VPN connection in GCP.
!
! #2: NAT exemption
!
! The name "GCP-NET" must be unique for the Cisco ASA/ASAv device.
!
object-group network GCP-NET
description GCP Virtual Network
network-object { gcp_network_address } { gcp_network_mask }
! The name "ONPREM-NET" must be unique for the Cisco ASA/ASAv device.
object-group network ONPREM-NET
description OnPrem Network
network-object { macstadium_network_address } { macstadium_network_mask }
! The names "gcp-in", "gcp-acl", and "gcp-filter" must be unique for the Cisco ASA/ASAv device.
access-list gcp-in extended permit ip host { gcp_vpn_ip } host { macstadium_public_ip }
access-list gcp-acl extended permit ip any4 object-group GCP-NET
access-list gcp-filter extended permit ip object-group GCP-NET object-group ONPREM-NET
nat ({ macstadium_network_name },{ macstadium_outside_interface }) 1 source static ONPREM-NET ONPREM-NET destination static GCP-NET GCP-NET
! #3: IKE & IPSec configuration
!
! The name "gcp" must be unique for the Cisco ASA/ASAv device.
crypto ipsec ikev2 ipsec-proposal gcp
protocol esp encryption aes-256
protocol esp integrity sha-1
! The name "gcp-vpn-map" must be unique for the Cisco ASA/ASAv device.
crypto map gcp-vpn-map 1 match address gcp-acl
crypto map gcp-vpn-map 1 set pfs group14
crypto map gcp-vpn-map 1 set peer { gcp_vpn_ip }
crypto map gcp-vpn-map 1 set ikev2 ipsec-proposal gcp
crypto map gcp-vpn-map interface { macstadium_outside_interface }
crypto ikev2 policy 100
encryption aes-256
integrity sha512
group 14
prf sha
lifetime seconds 36000
exit
crypto ikev2 enable { macstadium_outside_interface }
crypto ipsec security-association lifetime seconds 10800
crypto ipsec security-association replay window-size 128
crypto ipsec security-association pmtu-aging infinite
crypto isakmp identity address
crypto isakmp disconnect-notify
no crypto isakmp nat-traversal
crypto ipsec df-bit clear-df Outside
group-policy gcp internal
group-policy gcp attributes
vpn-filter value gcp-filter
vpn-tunnel-protocol ikev2
tunnel-group { gcp_vpn_ip } type ipsec-l2l
tunnel-group { gcp_vpn_ip } general-attributes
default-group-policy gcp
tunnel-group { gcp_vpn_ip } ipsec-attributes
isakmp keepalive threshold 10 retry 3
ikev2 remote-authentication pre-shared-key { shared_key }
ikev2 local-authentication pre-shared-key { shared_key }
```
## Step 1: Get the configuration values
`{ gcp_network_address }`
This is the IP address of the GCP local network that needs to have access to Orka.
1. Verify that you're logged into the GCP console and you are working in the correct project.
![GCP console project selector in toolbar]()
2. From the GCP console sidebar, scroll to the *Networking* section and select **Hybrid Connectivity** > **VPN**.
![GCP Hybrid Connectivity VPN menu in sidebar]()
3. Select **Cloud VPN Gateways**.
4. Locate the gateway used by your GCP-Orka tunnel and note the value for **Region**.
![GCP Cloud VPN Gateways list showing gateway region and VPC network]()
5. Click the value listed under **VPC network**.\
The GCP console redirects you to the list of subnets for the selected network.
6. In the list of subnets, locate the one matching the region you noted in **Step 4**.
7. From the respective **IP address ranges** field, use the IP address without the bit notation at the end (e.g. `/16`).
`{ gcp_network_mask }`
This is the subnet mask of the GCP local network that needs to have access to Orka.
1. Verify that you're logged into the GCP console and you are working in the correct project.
![GCP console project selector in toolbar]()
2. From the GCP console sidebar, scroll to the *Networking* section and select **Hybrid Connectivity** > **VPN**.
![GCP Hybrid Connectivity VPN menu in sidebar]()
3. Select **Cloud VPN Gateways**.
4. Locate the gateway used by your GCP-Orka tunnel and note the value for **Region**.
![GCP Cloud VPN Gateways list showing gateway region and VPC network]()
5. Click the value listed under **VPC network**.\
The GCP console redirects you to the list of subnets for the selected network.
6. In the list of subnets, locate the one matching the region you noted in **Step 4**.
7. From the respective **IP address ranges** field, use the bit notation at the end (e.g. `/16`) and convert it to a subnet mask. You can use a CIDR calculator such as this [CIDR/Netmask Lookup Tool](https://www.ultratools.com/tools/netMask).
`{ gcp_vpn_ip }`
This is the public IP address of the cloud VPN gateway in GCP.
1. Verify that you're logged into the GCP console and you are working in the correct project.
![GCP console project selector in toolbar]()
2. From the GCP console sidebar, scroll to the *Networking* section and select **Hybrid Connectivity** > **VPN**.
![GCP Hybrid Connectivity VPN menu in sidebar]()
3. Select **Cloud VPN Gateways**.
4. Locate the gateway used by your GCP-Orka tunnel and use the value listed under **IP address**.
![GCP Cloud VPN Gateways list showing public IP address]()
`{ macstadium_network_name }`
This is `Private-1`.
`{ macstadium_network_address }`
This is the IP address of the `Private-1` network, from the `Private-1` row of the **IP Allocation** table in My Cloud.
`{ macstadium_network_mask }`
This is the subnet mask of the `Private-1` network, from the `Private-1` row of the **IP Allocation** table in My Cloud.
`{ macstadium_public_ip }`
This is your firewall's public IP (the `FW1-Outside` address), shown at the top of the firewall's section in My Cloud.
`{ macstadium_outside_interface }`
This is `Outside`.
`{ shared_key }`
This is the IPSec pre-shared key used when creating the VPN connection in GCP.
* You must have this key saved separately.
## Step 2: Complete the template
1. Copy the template into a text editing tool.
2. Replace all placeholders with their respective values.
3. Delete the remaining commented lines to clean up the template. Commented lines are indicated by `! `at the beginning of the line.
4. Save your changes.
# 3. Orka side of the AWS VPN tunnel
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/3-aws-orka-side-of-the-vpn-tunnel
Apply the prepared AWS VPN config to your Orka Cisco ASAv via ASDM-IDM. Completes the Orka side of the AWS site-to-site IPsec tunnel.
How to set up the Orka side of your AWS-Orka tunnel to enable two-way access between your AWS and Orka VMs.
**Before you begin:** You need an active VPN connection to your Orka cluster, your Cisco ASAv connection information (the firewall's public IP and **Credentials**) from [My Cloud](/macstadium/macstadium-overview/ip-plan), and the downloaded and prepared [VPN configuration file](/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file).
After you [have created your VPN tunnel in Amazon](/orka/networking-with-orka-at-macstadium/1-aws-side-of-the-vpn-tunnel) and you [have prepared the configuration file](/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file), you need to apply the configuration to the Cisco ASAv in your Orka cluster.
1. [Run Cisco ASDM-IDM and log in.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
2. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
3. Select **Multiple Line**.
4. Type [configure terminal](https://www.cisco.com/c/m/en_us/techdoc/dc/reference/cli/n5k/commands/configure-terminal.html), press `Enter`, and paste the contents of the [prepared VPN configuration file](/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file).
5. Click **Send**.
# 3. Orka Side of the GCP VPN Tunnel
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/3-orka-side-of-the-gcp-vpn-tunnel
Apply the GCP VPN config to your Orka cluster's Cisco ASA/ASAv via Cisco ASDM-IDM. Completes the Orka side of the GCP site-to-site IPsec tunnel.
How to set up the Orka side of your GCP-Orka tunnel to enable two-way access between your GCP and Orka VMs.
**Before you begin:** You need an active VPN connection to your Orka cluster, your Cisco ASAv connection information (the firewall's public IP and **Credentials**) from [My Cloud](/macstadium/macstadium-overview/ip-plan), and the downloaded and prepared [VPN configuration file](/orka/networking-with-orka-at-macstadium/2-gcp-vpn-tunnel-configuration-file).
After you [have created your site-to-site VPN connection in Google Cloud Platform (GCP)](/orka/networking-with-orka-at-macstadium/1-gcp-side-of-the-vpn-tunnel) and you [have prepared the configuration](/orka/networking-with-orka-at-macstadium/2-gcp-vpn-tunnel-configuration-file) for use, you need to apply the required changes to the Cisco ASA/ASAv device in your Orka environment.
1. [Run Cisco ASDM-IDM and log in.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
2. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
3. Select **Multiple Line**.
4. Type [`configure terminal`](https://www.cisco.com/c/m/en_us/techdoc/dc/reference/cli/n5k/commands/configure-terminal.html), press `Enter`, and paste the contents of the [prepared VPN configuration file](/orka/networking-with-orka-at-macstadium/2-gcp-vpn-tunnel-configuration-file).
5. Click **Send**.
# 4. Verifying the AWS VPN tunnel
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/4-aws-verifying-the-vpn-tunnel
(Optional) How to verify that your AWS-Orka VPN tunnel works as expected: check security associations, tunnel status and traffic between Orka and AWS.
(Optional) How to verify that your AWS-Orka VPN tunnel works as expected: check security associations, tunnel status and traffic between Orka and AWS.
**You need:**
* Active VPN connection to your Orka cluster.
* Your Cisco ASAv connection information (the firewall's public IP and **Credentials**) from [My Cloud](/macstadium/macstadium-overview/ip-plan).
This part of the workflow is optional.
## Verify that there is an ISAKMP security association between the peers
1. [Run Cisco ASDM-IDM and log in to your firewall.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
2. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
3. Select **Single Line**, enter the [following command](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#isakmp_sa), and click **Send**.
```
show crypto isakmp sa
```
If the site-to-site VPN connection is configured properly, you should see information about an active IKEv1. For example:
```
Result of the command: "show crypto isakmp sa"
IKEv1 SAs:
Active SA: 1
Rekey SA: 0 (A tunnel will report 1 Active and 1 Rekey SA during rekey)
Total IKE SA: 1
1 IKE Peer: ...
Type : L2L Role : initiator
Rekey : no State : MM_ACTIVE
There are no IKEv2 SAs
```
## Verify that there is an IPsec security association between peers
1. [Run Cisco ASDM-IDM and log in to your firewall.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
2. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
3. Select **Single Line**, enter the [following command](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#ipsec_sa), and click **Send**.
```
show crypto ipsec sa
```
If the site-to-site VPN connection is configured properly, you should see a detailed log. For example:
```
Result of the command: "show crypto ipsec sa"
interface: Outside
Crypto map tag: amzn_vpn_map_1, seq num: 1, local addr: ...
access-list acl-amzn extended permit ip any ...
local ident (addr/mask/prot/port): ...
remote ident (addr/mask/prot/port): ...
current_peer: ...
....
inbound esp sas:
...
outbound esp sas:
...
```
## Verify that the tunnel is up
Currently, Amazon lets you create a site-to-site VPN where at all times one tunnel is active (up) and one is passive (down). A monitoring service checks frequently if the active tunnel is up and, if not, brings the passive tunnel up instead. This ensures minimal downtime.
1. Log in to your AWS Management Console and access your VPC service. In the top right corner of the screen, make sure that you're working in the correct region.
2. In the sidebar, locate the **Virtual Private Network** menu and select **Site-to-Site VPN Connections**.
![AWS VPC sidebar with Site-to-Site VPN Connections selected]()
4. Select your VPN from the list and inspect the details at the bottom of the screen.
5. Click **Tunnel Details** and verify that one of the tunnels is up.
![AWS VPN Tunnel Details showing one tunnel status as Up]()
## Test traffic and visibility through the tunnel
[Amazon VPC Documentation: How to Test the Customer Gateway Configuration](https://docs.aws.amazon.com/vpc/latest/adminguide/Cisco_ASA.html#TestCustomerGateway_ASA)
# 4. Verifying the GCP VPN Tunnel
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/4-verifying-the-gcp-vpn-tunnel
(Optional) How to verify that your GCP-Orka VPN tunnel works as expected: check security associations, tunnel status and traffic between Orka and GCP.
(Optional) How to verify that your GCP-Orka VPN tunnel works as expected: check security associations, tunnel status and traffic between Orka and GCP.
**Before you begin:** You need an active VPN connection to your Orka cluster and your Cisco ASAv connection information (the firewall's public IP and **Credentials**) from [My Cloud](/macstadium/macstadium-overview/ip-plan).
This part of the workflow is optional.
## Verify that there is an ISAKMP security association between the peers
1. [Run Cisco ASDM-IDM and log in to your firewall.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
2. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
3. Select **Single Line**, enter the [following command](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#isakmp_sa), and click **Send**.
```
show crypto isakmp sa
```
If the site-to-site VPN connection is configured properly, you should see information about an active IKEv1. For example:
```
Result of the command: "show crypto isakmp sa"
IKEv1 SAs:
Active SA: 1
Rekey SA: 0 (A tunnel will report 1 Active and 1 Rekey SA during rekey)
Total IKE SA: 1
1 IKE Peer: ...
Type : L2L Role : initiator
Rekey : no State : MM_ACTIVE
There are no IKEv2 SAs
```
## Verify that there is an IPsec security association between peers
1. [Run Cisco ASDM-IDM and log in to your firewall.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
2. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
3. Select **Single Line**, enter the [following command](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html#ipsec_sa), and click **Send**.
```
show crypto ipsec sa
```
If the site-to-site VPN connection is configured properly, you should see a detailed log. For example:
```
Result of the command: "show crypto ipsec sa"
interface: Outside
Crypto map tag: amzn_vpn_map_1, seq num: 1, local addr: ...
access-list acl-amzn extended permit ip any ...
local ident (addr/mask/prot/port): ...
remote ident (addr/mask/prot/port): ...
current_peer: ...
....
inbound esp sas:
...
outbound esp sas:
...
```
## Verify that the tunnel is connected
1. Log in to your GCP console.
2. From the GCP console sidebar, scroll to the *Networking* section and select **Hybrid Connectivity** > **VPN**.
![GCP console Hybrid Connectivity VPN navigation]()
3. On the **Cloud VPN Tunnels** tab, locate the tunnel to MacStadium and check the value for **VPN tunnel status**. When your tunnel is properly connected, the status is: `Established`.
![GCP Cloud VPN Tunnels tab showing tunnel status as Established]()
## Test traffic and visibility through the tunnel
1. Verify that you have created a virtual machine in MacStadium.
2. Verify that you have created a virtual machine instance in GCP and that you have enabled user login on it.\
For more information about user login on GCP instances, see [Google Cloud Documentation: Setting up and configuring OS Login](https://cloud.google.com/compute/docs/instances/managing-instance-access).
3. In the terminal on your MacStadium VM, run the following command:
```
ssh @
```
Replace `` with the username for your GCP instance.\
Replace `` with the private IP of the GCP instance.
4. When prompted, provide your password or key for the specified username on the specified GCP instance.\
If the connection is successful, the prefix of the terminal becomes `@`. This indicates that you have connected from Orka to GCP over the tunnel.
5. Run the following command:
```
ssh @
```
Replace `` with the username for your Orka VM.\
Replace `` with the private IP of the Orka VM.
6. When prompted, provide your password or key for the specified username on the specified MacStadium VM.\
If the connection is successful, the prefix of the terminal becomes `@`. This indicates that you have connected from GCP to MacStadium over the tunnel.
# Connect AWS to your Orka cluster
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/aws-orka-connections
Connect AWS to your Orka cluster: one-time access from EC2 via VPN client, or a persistent IPsec site-to-site tunnel between your Amazon VPC and Orka.
Overview of how to connect AWS to your Orka cluster. Deep dive for detailed instructions on bringing up a tunnel between the two.
## One-Time Access
If you need to establish one-time or temporary access to your Orka cluster from a single virtual machine hosted in Amazon Web Services (AWS), you can [connect via VPN](/orka/networking-with-orka-at-macstadium/vpn-connection) from the AWS machine to your Orka cluster.
## VPN Tunnel
If you need to connect an entire Amazon Virtual Private Cloud (Amazon VPC) to your Orka cluster through a stable, persistent connection, you need to establish an IPsec site-to-site VPN between the two clouds (VPN tunnel):
1. [Create a Site-to-Site VPN for your Amazon VPC.](/orka/networking-with-orka-at-macstadium/1-aws-side-of-the-vpn-tunnel)
2. [Download and adjust the AWS-specific configuration file for the VPN.](/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file)
3. [Apply the configuration to your Cisco ASAv device using the Cisco ASDM-IDM.](/orka/networking-with-orka-at-macstadium/3-aws-orka-side-of-the-vpn-tunnel)
### You Can Also
* [Verify the VPN tunnel.](/orka/networking-with-orka-at-macstadium/4-aws-verifying-the-vpn-tunnel)
* [Perform VPN tunnel troubleshooting.](/orka/networking-with-orka-at-macstadium/aws-vpn-tunnel-troubleshooting)
# AWS VPN Tunnel Troubleshooting
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/aws-vpn-tunnel-troubleshooting
Fix AWS-to-Orka VPN tunnel issues: Cisco ASAv config errors, tunnel UP but no traffic, VPC route propagation problems, and NAT exemption mismatches.
What to look for when you're experiencing issues with your AWS-Orka VPN tunnel and how to perform basic troubleshooting.
## Errors during the Cisco ASAv configuration
* Sometimes, the command line interface might return errors about the `crypto isakmp policy` block of commands.\
**Workaround:** Ignore the errors. They do not affect the configuration.
* The command line interface returns `ERROR: unable to find interface “outside”`.\
**Workaround:** Sometimes, the command line interface is case-sensitive and you need to preserve the capitalization of the network configuration as provided in [My Cloud](/macstadium/macstadium-overview/ip-plan).
1. Clean up the firewall configuration.
2. [Rename outside in your configuration file to Outside.](/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file)
3. [Re-run the complete configuration in Cisco ASDM-IDM.](/orka/networking-with-orka-at-macstadium/3-aws-orka-side-of-the-vpn-tunnel)
## The tunnel is UP but there's no traffic between AWS and Orka
If Amazon shows that one tunnel is UP but there's no traffic between AWS and your Orka cluster, it might be because of some common mistakes when preparing the configuration file. Check for the following:
### AWS checks
All checks in this section are performed in the AWS Management Console.
### Verify that your virtual private gateway is attached to the VPC
1. Log in to your AWS Management Console and access your VPC service. In the top right corner of the screen, make sure that you're working in the correct region.
2. In the VPC service sidebar, locate the **Virtual Private Network** menu and select **Virtual Private Gateways**.
![AWS VPC sidebar with Virtual Private Gateways selected]()
3. On the **Virtual Private Gateways** dashboard, check the status of the virtual private gateway used in your tunnel.
4. If the virtual private gateway is detached, right-click it and select **Attach to VPC**.
![Right-click menu on virtual private gateway showing Attach to VPC option]()
Verify that the [route tables](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html) for the Amazon Virtual Private Cloud (Amazon VPC) propagate traffic for the virtual private gateway you're using.
1. Log in to your AWS Management Console and access your VPC service. In the top right corner of the screen, make sure that you're working in the correct region.
2. In the VPC service sidebar, locate the **Virtual Private Cloud** menu and select **Route Tables**.
![AWS VPC sidebar with Route Tables selected]()
3. In the list of routing tables, select the main table.
1. At the bottom of the screen, select **Route Propagation** and make sure that the propagation is enabled. If your virtual private gateway is not listed, make sure that it's attached to the VPC.
2. If propagation is disabled, click **Edit route propagation**.
3. Select the **Propagate** checkbox and click **Save**.
![AWS Route Propagation tab showing propagation enabled for virtual private gateway]()
### Cisco ASAv checks
All checks in this section are performed against the [VPN configuration file](/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file).
Verify that you've replaced `` and `` with the correct values for the `Private-1` network, from the `Private-1` row of the **IP Allocation** table in My Cloud.
Verify that you've configured the NAT exemption rule properly.
* The host and subnet mask required for `obj-SrcNet` are the host and mask for the `Private-1` network, from the **IP Allocation** table in My Cloud.
* The host and subnet mask required for `obj-amzn` are the host and mask for your Amazon VPC. You can find this information by logging into your AWS Management Console, navigating to your VPC dashboard, selecting your VPC, and checking the **Description** at the bottom of the screen. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the `/16` notation converts to a `255.255.0.0` subnet mask).
* The values in the brackets after `nat` must be (`Private-1`,`Outside`).
To resolve any of the listed common problems with the Cisco ASAv configuration, complete the following steps:
1. Clean up the firewall configuration.
2. Make the necessary changes to the [configuration file](/orka/networking-with-orka-at-macstadium/2-aws-vpn-tunnel-configuration-file).
3. [Re-run the complete configuration in Cisco ASDM-IDM.](/orka/networking-with-orka-at-macstadium/3-aws-orka-side-of-the-vpn-tunnel)
## There's traffic between AWS and Orka but you cannot access the Orka VM from AWS
Sometimes, you might be able to establish an SSH connection from an Orka VM to a VM in AWS but you might not be able to see or access the Orka VM from AWS.
This might be because SSH (Remote Login) is not enabled within the Orka VM.\
Verify that SSH is enabled for the Orka VM.
## There's traffic from AWS to Orka but you cannot access AWS from Orka
Sometimes, you might be able to establish an SSH connection from AWS to an Orka VM but you might not be able to see or access AWS from an Orka VM.
This might be due to AWS being configured to stop inbound traffic.\
For information about how to enable inbound traffic, see [Amazon VPC Documentation: Security Groups for Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) and [Amazon VPC Documentation: Network ACLs](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html).
## Troubleshooting
### Cleaning up the ASAv configuration
Sometimes, you might need to clean up the Cisco ASAv configuration and start over.
1. [Verify that you are connected via VPN to your Orka cluster.](/orka/networking-with-orka-at-macstadium/vpn-connection)
2. [Run Cisco ASDM-IDM and log in to the firewall.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
3. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select **Single Line**.
5. Run the following commands one by one, clicking **Send** in between. Replace the placeholders with their respective values. Use **Table 1: Placeholders** for reference.
```
clear configure tunnel-group
clear configure tunnel-group
clear configure group-policy
clear configure crypto map
clear configure access-list
clear configure access-list amzn-filter
clear configure access-list acl-amzn
clear configure crypto ipsec transform-set transform-amzn
clear configure sla monitor 1
no nat (Private-1,Outside) 1 source static obj-SrcNet obj-SrcNet destination static obj-amzn obj-amzn
no object network obj-SrcNet
no object network obj-amzn
```
**Table 1: Placeholders**
| Placeholder | Value | Description |
| --------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `` | (Sample) `192.168.0.0` | The IP of the tunnel, configured with the first set of `tunnel-group` commands in the Amazon configuration file. |
| `` | (Sample) `192.168.0.2` | The IP of the tunnel, configured with the second set of `tunnel-group` commands in the Amazon configuration file. |
| `` | By default: `filter` | The name of the policy configured with the `group-policy` commands in the Amazon configuration file. |
| `` | By default: `amzn_vpn_map` | The name of the crypto map configured with the `crypto map` commands in the Amazon configuration file. |
| `` | By default: `outside_access_in` | The unique name of the access control list created with the configuration file in the Amazon configuration file. |
## More troubleshooting by Amazon
[Amazon VPC Documentation: Troubleshooting Cisco ASA Customer Gateway Connectivity](https://docs.aws.amazon.com/vpc/latest/adminguide/Cisco_ASA_Troubleshooting.html).
## More troubleshooting by Cisco
[Cisco Documentation: IPsec Troubleshooting](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html).
# Built-In Orka Domains
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/built-in-orka-domains
Use your company.orka.app domain instead of raw Orka API IPs. Covers hosts file setup, HTTPS access, and certificate trust for the Orka API.
MacStadium provides built-in TLS-enabled domains (Orka domains). Learn how to work with your own built-in Orka domain.
You can use an Orka domain (such as company.orka.app) to access your Orka environment instead of the default Orka endpoints (10.221.188.100 or 10.221.188.20). Starting with Orka 1.5.4, Orka domains are available to all users by default.
Built-in Orka domains provide improved security. They are TLS-enabled and require access via HTTPS.
## 1. Configure your connection
To be able to reach your Orka domain, you need to add the cluster [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) IP and the Orka domain name to your hosts file.
#### **What's your Ingress IP?**
If you reach your Orka endpoint at *.*.*.20, the Ingress IP is *.*.*.22.
For example: 10.221.188.22.
If you reach your Orka endpoint at *.*.*.100, the Ingress IP is *.*.*.241.
For example: 10.221.188.241.
### macOS and Linux
1. In the Terminal, run the following command:
```
sudo nano /etc/hosts
```
2. When prompted, provide your password.
3. At the bottom of the file, on a new line, add the Ingress IP and the Orka domain, separated by a space.
```
For example:
10.221.188.22 company.orka.app
```
4. Press Ctrl+0 and then press Enter to save your changes.
5. Press Ctrl+X to exit nano.
6. (Optional, macOS) If you cannot reach your Orka domain, try flushing the DNS cache.
```
dscacheutil -flushcache
```
### Windows
1. Press the Windows key and type Notepad in the search text box.
2. Right-click the Notepad icon and select Run as administrator.
3. In Notepad, select File > Open.
4. In the File name text box, type C:\Windows\System32\drivers\etc\hosts.
5. At the bottom of the file, on a new line, add the Ingress IP and the Orka domain, separated by a space.
```
For example:
10.221.188.22 company.orka.app
```
6. Save your changes and close the file.
## 2. Use the Orka domain in your day-to-day work
You can use your Orka API endpoint ([http://10.221.188.20](http://10.221.188.20) or [http://10.221.188.100](http://10.221.188.100)) and your Orka domain ([https://company.orka.app](https://company.orka.app)) interchangeably in your workflows.
1. If you don't know what your Orka domain is, contact the MacStadium team.
2. Configure your Orka tools to target the Orka domain. Note that you need to use https with your Orka domain.
* For the Orka API, change your API requests to target `https://`.
* For the Orka3 CLI, run `orka3 config set --api-url https://`.
* For the Orka Web UI, open `https://` in your browser.
* For CI/CD integrations, switch to `https://` in the respective plugin configuration.
## 3. (Orka API-only) Download and trust the Orka domain certificate
To be able to run API calls against your Orka domain, you need to download the certificate for the Orka domain locally and add it to your trusted certificates.
To download the certificate, complete the following steps:
1. Open Firefox and navigate to `https://`.
2. Click the padlock icon in the address bar. In the pop-up, click Connection secure and then More information.
3. In the Page Info dialog, click View Certificate.
4. Scroll down and locate the PEM download section. Download the PEM (cert) file.
### macOS
1. Open Keychain Access.
2. Drag and drop the downloaded certificate to the login keychain.
3. Double-click the newly added certificate.
4. Expand the Trust section and for the When using this certificate setting, select Always Trust.
5. Close the certificate info window and when prompted, provide your password.
## Linux
Run the following commands:
```
sudo mkdir /usr/local/share/ca-certificates/extra
sudo cp mycertificate.pem /usr/local/share/ca-certificates/extra/mycertificate.crt
sudo update-ca-certificates
```
### Windows
1. Rename the downloaded certificate and change its extension to .crt.
2. Double-click the file and confirm that you want to open it.
3. On the General tab, click Install Certificate.
4. For Store Location, select Local Machine and click Next.
5. When prompted, confirm that you want Windows host process to make changes to your device.
6. Select Place all certificates in the following store, click Browse and from the list, select Trusted Root Certification Authorities and click OK.
7. Click Next, review the settings, and click Finish.
# External Custom Domains
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/external-custom-domains
Configure a custom domain for your Orka cluster using a TLS certificate. Covers certificate upload, domain mapping, Ingress configuration, and tool setup.
Instead of working with the default Orka endpoints (10.221.188.20 or 10.221.188.100) or your built-in Orka domain (company.orka.app), you can access your cluster from an external custom domain (for example: company.com).
Custom domains provide an additional level of security and compliance. To configure an external custom domain for your cluster, you need a TLS certificate. With a valid TLS certificate in place, you need to access your cluster via HTTPS.
## Overview
To configure an external custom domain for your Orka cluster, you need to complete the following tasks.
1. Obtain a TLS certificate and a private key for the domain.
2. Upload the certificate to the cluster.
3. Map the custom domain and the Ingress of your cluster.
4. Trust the certificate on your local machine.
5. Configure your tools.
## Limitations
* You can have only one custom TLS certificate uploaded to your cluster at a time. Subsequent uploads replace the current custom TLS certificate.
## 1. Obtain a certificate
Before you begin, you must have your own certificate and private key file that meet the following requirements:
* Both files are in PEM format.
* The private key is not passphrase protected.
* The certificate might be any of the following:
* A single domain certificate (e.g. company.com).
* Multi-domain certificate (e.g. app1.company.com, app2.company.com, and so on).
* Wildcard TLS certificate (e.g. \*.company.com)
* If containing an asterisk, it must be a single asterisk and must be in the leftmost position of the domain name. For example: You cannot use a *.*.company.com certificate to work with Orka.
* A certificate chain (bundle) that contains your server, intermediates, and root certificates concatenated (in the proper order) into one file.
* The certificate must be a registered domain certificate issued by a certificate authority OR a self-signed certificate for any domain (for local use only).
## 2. Upload the certificate
Next, you need to upload the custom TLS certificate and private key to your cluster.
1. Connect to your cluster via [VPN](/orka/networking-with-orka-at-macstadium/vpn-connection).
2. Make sure you are authenticated with your cluster as an administrator. Run `orka3 login` if you haven't already.
3. Send the following POST request to /api/v1/upload/cert.
```
curl -X POST '/api/v1/upload/cert' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer ' \
--form 'certPath=@' \
--form 'keyPath=@'
```
Replace `` with your Orka API URL (for example, `http://10.221.188.20`).
Replace `` with your Orka API token.
Replace `` and `` with the full paths to the certificate and the private key on your local machine.
## 3. Map the domain to your cluster Ingress
Next, map your external custom domain and your cluster. You need to map the domain and the IP of the cluster [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).
#### **What's your Ingress IP?**
If you reach your Orka endpoint at *.*.*.20, the Ingress IP is *.*.*.22.
For example: 10.221.188.22.
If you reach your Orka endpoint at *.*.*.100, the Ingress IP is *.*.*.241.
For example: 10.221.188.241.
### 3.1 Create a global mapping
If you are working with a registered domain and a TLS certificate obtained from a certificate authority, you can configure a global mapping. You need to add A/AAAA record in the DNS settings of the domain. This A/AAAA record must map the external custom domain name to the Orka Ingress IP.
### 3.2 Create a local mapping
If you want to work with an external custom domain locally and you are using a self-signed TLS certificate, you can map the domain to the Ingress IP in your hosts file.
**macOS and Linux**
1. In the Terminal, run the following command:
```
sudo nano /etc/hosts
```
2. When prompted, provide your password.
3. At the bottom of the file, on a new line, add the Ingress IP and the custom Orka domain, separated by a space.
```
For example:
10.221.188.22 company.com
```
4. Press Ctrl+0 and then press Enter to save your changes.
5. Press Ctrl+X to exit nano.
6. (Optional, macOS) If you cannot reach your custom Orka domain, try flushing the DNS cache.
```
dscacheutil -flushcache
```
**Windows**
1. Press the Windows key and type Notepad in the search text box.
2. Right-click the Notepad icon and select Run as administrator.
3. In Notepad, select File > Open.
4. In the File name text box, type C:\Windows\System32\drivers\etc\hosts.
5. At the bottom of the file, on a new line, add the Ingress IP and the custom Orka domain, separated by a space.
```
For example:
10.221.188.22 company.com
```
6. Save your changes and close the file.
## 4. Trust the certificate locally
This step is required for self-signed certificates. If you are using a TLS certificate for a registered domain, issued by a recognized certificate authority, you can skip this step.
If you are using a self-signed certificate, you need to add your custom TLS certificate and trust it on all systems that will be accessing your Orka cluster. For some browsers, you might need to add the certificate (if self-signed) to the trusted store of the browser as well.
### macOS
1. Open Keychain Access.
2. Drag and drop the certificate to the login keychain.
3. Double-click the newly added certificate.
4. Expand the Trust section and for the When using this certificate setting, select Always Trust.
5. Close the certificate info window and when prompted, provide your password.
## Linux
Run the following commands:
```
sudo mkdir /usr/local/share/ca-certificates/extra
sudo cp mycertificate.pem /usr/local/share/ca-certificates/extra/mycertificate.crt
sudo update-ca-certificates
```
### Windows
1. Rename the certificate and change its extension to .crt.
2. Double-click the file and confirm that you want to open it.
3. On the General tab, click Install Certificate.
4. For Store Location, select Local Machine and click Next.
5. When prompted, confirm that you want Windows host process to make changes to your device.
6. Select Place all certificates in the following store, click Browse and from the list, select Trusted Root Certification Authorities and click OK.
7. Click Next, review the settings, and click Finish.
## 5. Configure your tools
### Known limitation
Due to Node.js limitations, the Orka CLI can work only with valid TLS certificates issued by [the certificate authorities recognized by Node.js](https://github.com/nodejs/node/blob/main/src/node_root_certs.h). If you are using a self-signed certificate or your certificate was issued by a certificate authority unrecognized by Node.js, you need to use your Orka API endpoint ([http://10.221.188.20](http://10.221.188.20) or [http://10.221.188.100](http://10.221.188.100)) with the Orka CLI, or switch to another Orka tool.
Finally, you need to target your external custom domain with your Orka tools. Note that you need to use https with your custom TLS domain.
* For the Orka API, change your API requests to target `https://`.
* For the Orka3 CLI, run `orka3 config set --api-url https://`. Note that you can use only valid TLS certificates issued by a limited number of certificate authorities.
* For the Orka Web UI, open `https://` in your browser.
* For CI/CD integrations, switch to `https://` in the respective plugin configuration.
You can use your Orka API endpoint ([http://10.221.188.20](http://10.221.188.20) or [http://10.221.188.100](http://10.221.188.100)) and your custom domain ([https://company.com](https://company.com)) interchangeably in your workflows.
# Connect GCP to your Orka cluster
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/gcp-orka-connections
Connect GCP to your Orka cluster: one-time access from a GCP VM via VPN client, or a persistent IPsec site-to-site tunnel between your GCP cloud and Orka.
Overview of how to connect GCP to your Orka cluster. Deep dive for detailed instructions on bringing up a tunnel between the two.
## One-Time Access
If you need to establish one-time or temporary access to your Orka cluster from a single virtual machine hosted in Google Cloud Platform (GCP), you can [connect via VPN](/orka/networking-with-orka-at-macstadium/vpn-connection) from the GCP machine to your Orka cluster.
## VPN Tunnel
If you need to connect an entire GCP private cloud to your Orka cluster through a stable, persistent connection, you need to establish an IPsec site-to-site VPN between the two clouds (VPN tunnel):
1. [Create a Site-to-Site VPN for your GCP private cloud.](/orka/networking-with-orka-at-macstadium/1-gcp-side-of-the-vpn-tunnel)
2. [Download and adjust the GCP-specific configuration file for the VPN.](/orka/networking-with-orka-at-macstadium/2-gcp-vpn-tunnel-configuration-file)
3. [Apply the configuration to your Cisco ASAv device using the Cisco ASDM-IDM.](/orka/networking-with-orka-at-macstadium/3-orka-side-of-the-gcp-vpn-tunnel)
### You Can Also
* [Verify the GCP VPN tunnel.](/orka/networking-with-orka-at-macstadium/4-verifying-the-gcp-vpn-tunnel)
* [Perform GCP VPN tunnel troubleshooting.](/orka/networking-with-orka-at-macstadium/gcp-vpn-tunnel-troubleshooting)
# GCP VPN Tunnel Troubleshooting
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/gcp-vpn-tunnel-troubleshooting
Fix GCP-to-Orka VPN tunnel issues: Cisco ASA interface name errors, no-traffic tunnels, NAT exemption mismatches, and GCP firewall ingress rules.
What to look for when you're experiencing issues with your GCP-Orka VPN tunnel and how to perform basic troubleshooting.
## Unrecognized interface during the Cisco ASA/ASAv configuration
Sometimes, the command line interface might return `ERROR: unable to find interface “outside”`. The command-line interface might be case-sensitive and you might need to preserve the capitalization of the Orka network configuration as provided in [My Cloud](/macstadium/macstadium-overview/ip-plan).
1. Clean up the ASA configuration.\
For more information, see Cleaning up the ASA/ASAv configuration.
2. Rename `outside` in your configuration to `Outside`.
3. Re-run the complete configuration in Cisco ASDM-IDM.\
For more information, see [Setting Up the Orka Side of the Site-to-Site VPN](/orka/networking-with-orka-at-macstadium/3-orka-side-of-the-gcp-vpn-tunnel).
## The tunnel is connected but there's no traffic between GCP and Orka
If GCP shows that the tunnel is `Established` but there is no visibility and connectivity between the two clouds, it might be because of some common mistakes when preparing the configuration. Check for the following in the site-to-site VPN configuration. For more information, see [Preparing the VPN Configuration for Input into Cisco ASA/ASAv](/orka/networking-with-orka-at-macstadium/3-orka-side-of-the-gcp-vpn-tunnel).
* Verify that your `{ shared_key }` is correct. The `{ shared_key }` in the configuration must match the key set for the VPN connection.
* Verify that you've replaced `{ macstadium_network_address }` and `{ macstadium_network_mask }` with the correct values for the `Private-1` network, from the `Private-1` row of the **IP Allocation** table in My Cloud.
* Verify that you've configured the NAT exemption rule properly.
* The host and subnet mask required for `ONPREM-NET` are the host and mask for the `Private-1` network, from the **IP Allocation** table in My Cloud.
* The host and subnet mask required for `GCP-NET` are the host and mask for your GCP virtual network. You need to convert the [subnet mask bit notation](http://www.steves-internet-guide.com/subnetting-subnet-masks-explained/) to the correct subnet mask (e.g., the `/16` notation converts to a `255.255.0.0` subnet mask).
* The values in the brackets after `nat` must be the `Private-1`, followed by `Outside`.
To resolve any of the listed common problems with the Cisco ASA/ASAv configuration, complete the following steps:
1. Clean up the firewall configuration.
2. Make the necessary changes to the [configuration](/orka/networking-with-orka-at-macstadium/2-gcp-vpn-tunnel-configuration-file).
3. [Re-run](/orka/networking-with-orka-at-macstadium/3-orka-side-of-the-gcp-vpn-tunnel) the complete configuration in Cisco ASDM-IDM.
## There's traffic from GCP to Orka but you cannot access GCP from Orka
Sometimes, you might be able to establish an SSH connection from GCP to Orka but you might not be able to see or access GCP from Orka. This might be due to any of the following issues:
* The GCP firewall is not configured to allow ingress traffic.\
For information about how to enable ingress traffic, see [Google Cloud Documentation: Configuring firewall rules > Example configurations](https://cloud.google.com/vpn/docs/how-to/configuring-firewall-rules#example_configurations).
* Your GCP instances don't allow OS login.\
For more information about user login on GCP instances, see [Google Cloud Documentation: Setting up and configuring OS Login](https://cloud.google.com/compute/docs/instances/managing-instance-access).
## Troubleshooting
### Cleaning up the ASAv configuration
Sometimes, you might need to clean up the Cisco ASAv configuration and start over.
1. [Verify that you are connected via VPN to your Orka cluster.](/orka/networking-with-orka-at-macstadium/vpn-connection)
2. [Run Cisco ASDM-IDM and log in to the firewall.](/iaas/cisco-firewalls/logging-into-cisco-firewall)
3. In the Cisco ASDM-IDM application toolbar, select **Tools** > **Command Line Interface...**.
![Cisco ASDM-IDM Tools menu with Command Line Interface option]()
4. Select **Single Line**.
5. Run the following commands one by one, clicking **Send** in between. Replace the placeholders with their respective values. Use **Table 1: Placeholders** for reference.
```
clear configure tunnel-group { gcp_vpn_ip }
clear configure group-policy gcp
clear configure access-list gcp-in
clear configure access-list gcp-acl
clear configure access-list gcp-filter
clear configure crypto map gcp-vpn-map
clear configure crypto ipsec ikev2 ipsec-proposal gcp
no nat ({ macstadium_network_name },{ macstadium_outside_interface }) 1 source static ONPREM-NET ONPREM-NET destination static GCP-NET GCP-NET
no object-group network GCP-NET
no object-group network ONPREM-NET
```
**Table 1: Placeholders**
| Placeholder | Value | Description |
| ---------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------- |
| `{ gcp_vpn_ip }` | (Sample) `192.168.0.0` | The public IP address of the cloud VPN gateway in GCP. |
| `{ macstadium_network_name }` | `Private-1` | The name of the `Private-1` network, as listed in the **IP Allocation** table in My Cloud. |
| `{ macstadium_outside_interface }` | `Outside` | The name of the outside interface of your Cisco ASA/ASAv device. By default, this is `Outside`. |
## More troubleshooting by Google
[Google Cloud Documentation: Cloud VPN Troubleshooting](https://cloud.google.com/vpn/docs/support/troubleshooting)
## More troubleshooting by Cisco
[Cisco Documentation: IPsec Troubleshooting](https://www.cisco.com/c/en/us/support/docs/security-vpn/ipsec-negotiation-ike-protocols/5409-ipsec-debug-00.html).
# MSDC Network Requirements
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/msdc-network-requirements
Network requirements for Orka clusters at MacStadium data centers in Atlanta, Dublin, and Las Vegas, including reserved address ranges and custom subnets.
This page applies to Orka clusters hosted at MacStadium data centers (Atlanta, Dublin, and Las Vegas). It does not apply to Orka on AWS or customer on-premises deployments.
MacStadium creates and manages the physical host network for MSDC-hosted Orka clusters. The default subnet is `10.221.188.0/23`. If your organization needs a different subnet to avoid conflicts with your own network topology, you can request one, but the choice is constrained by three reserved address ranges described below.
## Reserved address ranges
All three [RFC 1918](https://datatracker.ietf.org/doc/html/rfc1918) private blocks are in use at MSDC in some capacity. When requesting a custom subnet, it must fall within `10.0.0.0/8`.
| Block | Reserved for | Can be used for host network? |
| ---------------- | --------------------------------------------------- | ----------------------------- |
| `10.0.0.0/8` | Physical host networks (default: `10.221.188.0/23`) | Yes |
| `172.16.0.0/12` | MSDC storage network (SAN) | No |
| `192.168.0.0/16` | Calico pod network (Kubernetes internal) | No |
### Why `192.168.0.0/16` is off-limits
Orka uses [Calico](https://docs.tigera.io/calico/latest/about/) for pod networking. During cluster bootstrap, `kubeadm` assigns Calico the `192.168.0.0/16` block as its pod network CIDR. If physical Mac hosts are on any subnet within this block, Calico will route pod traffic to physical addresses and vice versa, causing intermittent or complete networking failures for VMs and Orka services.
### Why `172.16.0.0/12` is off-limits
MacStadium uses this block for the storage area network (SAN) at MSDC facilities. Placing host traffic in this range creates conflicts with storage connectivity.
Resolving either conflict after the cluster is live requires a full cluster rebuild. Contact MacStadium before the cluster is bootstrapped if there is any question about subnet selection.
## Requesting a custom subnet
If `10.221.188.0/23` conflicts with your organization's network (for example, your VPN or corporate routing overlaps with it), contact your MacStadium account team to request a different subnet. Any alternative must be a subnet within `10.0.0.0/8`.
## Checklist before bootstrapping
* [ ] Confirm the assigned host subnet falls within `10.0.0.0/8`
* [ ] Confirm it does not overlap with your VPN or corporate network
* [ ] If you need a different subnet, request it from MacStadium before cluster bootstrap
# Connect to your Orka cluster via VPN
Source: https://docs.macstadium.com/orka/networking-with-orka-at-macstadium/vpn-connection
Connect to your Orka cluster's Cisco ASAv via VPN with OpenConnect or Cisco AnyConnect. Required before managing VMs or configuring cluster networking.
## Before You Begin
* The VPN server address: your firewall's public IP, shown at the top of the firewall's section in [My Cloud](/macstadium/macstadium-overview/ip-plan).
* The VPN username and password: shown under **Credentials** in the firewall's section in My Cloud. Select **Show** to reveal them.
## When VPN is required
Your Orka cluster sits behind a dedicated Cisco ASAv firewall. VMs and the Orka management plane are on a private network and not reachable from the public internet without VPN.
| Scenario | VPN required? |
| ----------------------------------------------------------------------- | ----------------------------------------------------- |
| `orka3` CLI commands (deploy, list, delete VMs) | Yes |
| Orka web UI | Yes |
| SSH into a VM | Yes |
| VNC / Screen Sharing into a VM | Yes |
| CI/CD runner already inside your corporate network (routed through VPN) | Depends on your network topology |
| VDI end-user sessions via Citrix Workspace app | No (Citrix proxies the session over outbound TCP 443) |
VDI end users do not need a VPN client. Citrix Workspace app establishes the session outbound through Citrix Cloud. VPN is only required for administrators managing the Orka cluster itself.
To protect your environment, MacStadium deploys your Orka cluster with a dedicated [Cisco Adaptive Security Virtual Appliance (ASAv)](https://www.cisco.com/c/en/us/products/collateral/security/adaptive-security-virtual-appliance-asav/datasheet-c78-733399.html) firewall. Cisco ASAv runs the same software as physical Cisco ASAs and delivers full ASA firewall and VPN capabilities to the cloud.
MacStadium has pre-configured the firewall and has enabled VPN access. All you need to do is run a VPN client and provide the server address and credentials for the connection.
## (Open-Source Option) OpenConnect
#### **Why OpenConnect?**
If you are a predominantly CLI user, you might want to use [OpenConnect](https://www.infradead.org/openconnect/index.html) - an open-source VPN client available from the command line.
### Download and Install OpenConnect
* If you have Homebrew on your system, you can run `brew install openconnect` from your command line.
* If you're running on Windows, you can [download](https://www.infradead.org/openconnect/download.html) and [build](https://www.infradead.org/openconnect/building.html) the OpenConnect package yourself or you can use Cisco AnyConnect instead.
### Use OpenConnect
1. From your command line, run the following command. Replace `` with your firewall's public IP from My Cloud.
```
sudo openconnect --protocol=anyconnect
// OR if running on Windows
openconnect --protocol=anyconnect
```
2. Follow the prompts.
* On the immediate Password prompt, provide your sudo password (the password for your current computer user) and press Enter.
* On the Enter 'yes' to accept, 'no' to abort; anything else to view: prompt, type yes and press Enter.
* On the Username prompt, provide the VPN username from the firewall's **Credentials** in My Cloud and press Enter.
* On the Password prompt, provide the VPN password from the firewall's **Credentials** in My Cloud and press Enter.
When the connection is established, you will see a similar output:
![OpenConnect terminal output showing successful VPN connection]()
**TIP: Want to terminate the VPN connection?**
At any time press Ctrl+C on the command line.
## Cisco AnyConnect Secure Mobility Client
#### **Why Cisco AnyConnect?**
Cisco firewalls are designed to work with the [Cisco AnyConnect Secure Mobility Client](https://www.cisco.com/c/en/us/support/security/anyconnect-secure-mobility-client/tsd-products-support-series-home.html) as a VPN client. If you prefer a GUI VPN client or you're running on Windows, you might want to use Cisco AnyConnect.
### Download and Install Cisco AnyConnect
1. In your browser, navigate to your firewall's public IP from My Cloud. You might need to use https\://.
2. Ignore the certificate warning and proceed to the address.
3. When prompted, enter the VPN credentials from the firewall's **Credentials** in My Cloud.\\
![Cisco AnyConnect login prompt for server address and credentials]()
4. When prompted, download, install, and run the Cisco AnyConnect desktop client.
## Use Cisco AnyConnect
1. Run Cisco AnyConnect Secure Mobility Client.
2. When prompted, enter your firewall's public IP from My Cloud and click Connect.\\
![Cisco AnyConnect main screen with server address field]()
3. If prompted that an untrusted server was blocked, perform the following steps:
* Click Change Setting... and deselect Block connections to untrusted servers.
* Close the Preferences - VPN window.
* Click Connect again.\\
![Cisco AnyConnect Preferences with Block connections to untrusted servers option]()
4. If prompted that the server certificate is untrusted, click Connect Anyway.
5. When prompted, provide your login credentials and click OK.
# OCI Images: Deploy VMs
Source: https://docs.macstadium.com/orka/oci-images/oci-images-deploy-vms
Deploy an Orka VM from any OCI-compatible image by specifying the registry address. Private registries require credentials pre-configured in the namespace.
Using an OCI image in your workloads is as simple as just deploying a VM and specifying the address of the image in the registry. If you are working with a private registry, you need to have the [registry credentials configured in the respective namespace](/orka/oci-images/oci-images-manage-registry-credentials) before attempting to deploy.
#### **Orka CLI**
```
orka3 vm deploy --image /[:]
OR
orka3 vm deploy --image /[:] --namespace
```
#### **Orka API**
```
curl -X 'POST' \
'/api/v1/namespaces//vms' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
-H 'Content-Type: application/json' \
-d '{
"image": "/[:]"
}'
```
Note that you need to provide the registry path to the image name and optionally its tag. For example: ghcr.io/my-organization/orka-images/orka-arm:latest.
You can add as many or as few configuration options as you need, including a user-specified name. If you are using the Orka3 CLI, run orka3 vm deploy --help for more information. If you are using the Orka3 API, see [Deploy a VM](https://macstadium.github.io/orka-api-docs/#tag/VMs/operation/vmDeploy).
**Did you know?**
You can find MacStadium's public vanilla macOS images at [https://github.com/macstadium/orka-images.](https://github.com/macstadium/orka-images)
# OCI Images: Manage Registry Credentials
Source: https://docs.macstadium.com/orka/oci-images/oci-images-manage-registry-credentials
Store and manage OCI registry credentials in Orka with orka3 regcred. Add, override, and remove credentials per namespace for private registry access.
How to manage the credentials for working with OCI-compatible registries in Orka 3.0.
If you want to work with private OCI images, you need to manage the credentials for the respective registries locally in your cluster. Note that:
* You can store only one set of credentials per registry per namespace.
* You need to store every set of credentials in every namespace where you might need them.
* Only cluster administrators can manage the registry credentials.
Orka stores the registry credentials as a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/).
## List the Available Registry Credentials
#### **Orka CLI**
```
orka3 regcred list
OR
orka3 regcred list --namespace
```
#### **Orka API**
```
curl -X 'GET' \
'/api/v1/namespaces//secrets/registrycredentials' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
```
## Add Registry Credentials
Note that the `` for the registry must include the scheme, hostname, and (optionally) port. For example, [https://ghcr.io](https://ghcr.io) or [https://10.221.188.5:30080](https://10.221.188.5:30080).
#### **Orka CLI**
```
orka3 regcred add --username --password
OR
orka3 regcred add --username --password --namespace
```
#### **Orka API**
```
curl -X 'POST' \
'/api/v1/namespaces//secrets/registrycredentials/add' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{
"password": "",
"server": "",
"username": ""
}'
```
If you are adding a server address with the HTTP scheme, you need to allow working with insecure registries.
#### **Orka CLI**
```
orka3 regcred add --username --password --allow-insecure
```
#### **Orka API**
```
curl -X 'POST' \
'/api/v1/namespaces//secrets/registrycredentials/add' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{
"allowInsecure": true,
"password": "",
"server": "",
"username": ""
}'
```
In the Orka3 CLI you can also read the password via stdin.
#### **Orka CLI**
```
echo -n '' | orka3 regcred add --username --password-stdin
OR
orka3 regcred add --username --password-stdin <