Welcome to the documentation of 7777.
This repository is also the place to ask for support about 7777: open a new GitHub issue and detail your problem.
If you need to discuss a problem with a purchase or a license, contact us privately (our email address can be found in the footer of port7777.com).
7777 is bundled as a self-contained binary.
Download and install the Linux binary in /usr/local/bin:
wget -q https://releases.port7777.com/latest/linux/7777
chmod +x 7777
sudo mv 7777 /usr/local/binNote: we've had one report that Bitdefender on Ubuntu was deleting the 7777 executable. If that happens to you, please let us know. You can add 7777 to Bitdefender's exclusion list.
A Linux Alpine version is available under the https://releases.port7777.com/latest/alpine/7777 URL.
Note: Due to a limitation in pkg, running apk add libstdc++ libgcc is required with Linux Alpine.
Download and install the MacOS binary in /usr/local/bin:
curl -o 7777 https://releases.port7777.com/latest/macos/7777
chmod +x 7777
sudo mv 7777 /usr/local/bin7777 is also available via Brew: brew install 7777. Note: the Brew publication has been contributed by the community, and may not be updated as frequently as the other distribution methods.
If you have any macOS permission issues (the binary isn't approved by Apple), you can whitelist it manually in system preferences or via the CLI:
spctl --add /usr/local/bin/7777
# Approval can be later removed via
spctl --remove /usr/local/bin/7777Note: if you download the binary via a web browser instead of curl, macOS 15 will flag the file as unsafe and the spctl command will fail. To solve that, run xattr -d com.apple.quarantine 7777. If you download the binary via curl (as shown in the docs above) then you shouldn't face this problem.
Download the Windows 10 binary directly from https://releases.port7777.com/latest/windows/7777.exe or via the command line:
curl.exe -o 7777.exe https://releases.port7777.com/latest/windows/7777.exeThen run the 7777.exe program, for example using Git Bash.
7777 requires a valid license to run. To set it up, run:
7777 configure YOUR_LICENSEReplace YOUR_LICENSE with the license sent to you after your purchase on port7777.com (you will receive it by email). This command will store your license in a ~/.7777/license file on your machine.
If you prefer, you can also set your license in a PORT_7777_LICENSE environment variable.
To connect to a database in your AWS account, 7777 requires AWS permissions.
By default, 7777 behaves like the official aws CLI and picks up any AWS account configured on your machine in the ~/.aws/credentials file. That means that if you use the AWS CLI, 7777 should work out of the box.
If you want to use a specific AWS profile, set the AWS_PROFILE variable. For example:
AWS_PROFILE=my-profile 7777If you prefer, you also can provide AWS access keys explicitly via the following environment variables:
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYYou can find the list of IAM permissions here if you create access keys specific to 7777.
To use 7777 to connect to an AWS RDS database, simply run 7777:
7777
# Use the --verbose flag to show more details
7777 --verbose
# Use the --region option to force a specific region
7777 --region=us-east-1The first time, 7777 will setup the strict minimum it requires to run in your AWS account (the list is detailed below).
7777 will then look at all the available databases and let you select which one to connect to.
Then, 7777 will establish a secure connection (also called "tunnel") between your computer and the AWS database. As long as 7777 is running, the connection will remain active.
By default, the database will be accessible through port 7777 on your computer.
The database can be accessed through localhost via port 7777, using the credentials you use in production.
Some database clients offer the option to connect via an SSH connection: this is not needed as 7777 already took care of that. Just point your client to 127.0.0.1:7777.
For example, using the CLI MySQL client:
mysql --user=admin --password=XXX --host=127.0.0.1 --port=7777A list of all commands and options is available here.
The AWS region can be customized via the 7777 --region=us-east-1 option.
Starting on 1.1.0, 7777 will now support Elasticache for Redis.
In order to establish a connection to your Redis Cluster, a new
parameter --elasticache has been added. Make sure you have (permission to list Elasticache instances)[https://github.com/whilenull/7777-support/blob/main/AWS-permissions.md#upgrading-from-10].
After the tunnel is established you may connect to your Redis cluster using any tool you like on your local port 7777
redis-cli -p 7777It is possible to run 7777 in Docker, as well as use it in CI/CD.
See the CI/CD documentation.
7777 lets you connect to a remote database running in the cloud via a port on your machine. This is possible through something called an SSH tunnel.
SSH is a secure protocol and SSH tunnels are a way to use that protocol to forward ports from one machine to another one.
Here, we forward port 7777 of your computer to the port of your database running in the cloud.
7777's job is then to setup everything needed, and then start the SSH tunnel. Here it is in more details:
Start a jump server (also known as "bastion") in the VPC.
This server is used for the SSH tunnel to allow your computer to access the RDS database. Indeed, that database is not publicly accessible.
The jump server is actually a Fargate container, which is more lightweight than an EC2 instance. It is also much cheaper since we only pay when the container is running (i.e. when 7777 runs).
Start an SSH server (sshd daemon) in the jump server.
Generate a unique private and public SSH key and set it up on the SSH server.
By using random and autogenerated SSH keys, we don't need one for you and we keep things secure by not reusing the same key multiple times.
Start the SSH tunnel from port 7777 on your machine to the database, via the jump server.
When you stop 7777 via Ctrl+C, the SSH tunnel and the Fargate container are stopped and destroyed.
If you connect to your database for 10 minutes, then you would only pay for 10 minutes of Fargate, which is $0.002 (0.2 cents).
In order to provide a cheap, secure, and fast tunnel to databases, 7777 uses serverless Fargate containers as "jump servers".
You don't have to understand or even care about all of this, but in case you want to know, here is what 7777 sets up on the first run:
Then, each time 7777 runs and the connection is active, the following AWS resources run:
You can easily review all those resources as they are grouped in a single CloudFormation stack: search for port7777 in the AWS CloudFormation console.
To remove everything that 7777 has set up in your AWS account, run:
7777 uninstallYou can also delete everything manually by deleting the port7777 CloudFormation stack in the AWS console. To find it, open the CloudFormation console and search for port7777 (make sure to select the correct region), then delete it.
Note: your databases will not be deleted. Only what 7777 used to create the tunnel is deleted. Just to be clear one last time: your database is safe.
Conflicts with other tools deleting changes made by 7777.
Some tools, like Terraform, can sometimes overwrite changes made by 7777. For example, they could remove from your database the security group that 7777 adds. In case that happens, this is very hard to detect and fix these issues because 7777 uses CloudFormation, which itself does not fix changes made externally to the CloudFormation stack.
One workaround is to run 7777 uninstall and 7777 again.
Error: There is no subnet routing to the internet in availability zone us-east-1a of VPC vpc-xxxxx.
This error can happen for applications that use the default VPC provided in the region. Those default VPCs are unfortunately not explicitely associated with the Route Table.
Not sure what that means or what to do? Please have a look at this answer, it should help. Get in touch if you have any issue.
The tunnel has been closed
If the container bastion (running in ECS Fargate) crashed for some reason, you can check out its logs in CloudWatch: