docs.sandstorm.io Open in urlscan Pro
2606:4700:20::681a:ef3  Public Scan

Form analysis
1 forms found in the DOM

GET ../../search.html

<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
  <input type="text" name="q" placeholder="Search docs" title="Type search term here">
</form>

Text Content

Docs Sandstorm.io »

 * Home

Using

 * Overview
 * Guided tour
 * Top bar
 * How it works
 * Security practices
 * Security non-events

Developing apps

 * Developer hub
 * What makes a good Sandstorm App?
 * Packaging apps with vagrant-spk
   * Installing vagrant-spk for package dev
   * Packaging tutorial
   * Packaging tutorial (Meteor)
   * Understanding & customizing vagrant-spk
   * Platform stacks
   * Code dependencies
   * Service dependencies
   * Troubleshooting
   * Debugging a running grain
 * Other packaging approaches
   * Raw packaging guide
   * Raw integration of Python
   * Raw integration of Ruby on Rails
   * Raw integration of pure client apps
 * Integrating your app with Sandstorm
   * User authentication & permissions
   * URLs, domain names, page titles
   * Exporting HTTP APIs
   * Web publishing
   * Connecting grains to each other & Sandstorm via the powerbox
   * Email from apps
 * App market publishing guide

Administering

 * Overview
 * Administrator's guide
 * Frequently asked questions
 * Installation
   * Installing & uninstalling
   * Troubleshooting a new install
   * Reference docs for install.sh
 * Demo mode
 * Backups
 * Networking configurations
   * Wildcard hosts
   * Sandcats dynamic DNS
   * HTTPS & SSL
   * Free sandcats.io HTTPS
   * Self-signed SSL
   * Reverse Proxy
   * Sharing the HTTPS Port
   * Email
   * Running Sandstorm offline
 * Reference docs for sandstorm.conf
 * Organizational Features
 * Active Directory integration
 * Running a Sandstorm hosting provider

Docs Sandstorm.io »
 * Docs »
 * Networking configurations »
 * Administering »
 * Sandcats dynamic DNS
 * Edit on GitHub

--------------------------------------------------------------------------------


ABOUT SANDCATS.IO

Sandcats.io is a free-of-cost dynamic DNS service run by the Sandstorm
development team. In a nutshell:

 * Sandstorm users can have a free domain name of the form example.sandcats.io.

 * Sandstorm can automatically set up that domain, including a valid HTTPS
   certificate for it.

 * It's an official part of Sandstorm and we recommend people use it!

In more detail:

 * Users host their own servers. A hostname like example.sandcats.io points at
   the IP address of someone's server, and that server holds its own private
   keys.

 * It assumes your server should be reachable from the global Internet.

 * It's an optional service. Keep reading this page to learn how to stop using
   it.

 * It points at your server's public (globally routable) IP address, which it
   auto-detects. Read elsewhere about setting up Sandstorm to use an internal IP
   address.

The purpose is to help people who run their own server have a working hostname
and HTTPS (TLS/SSL) certificate without having to think hard about the domain
name system or public key infrastructure.


FEATURES

Sandcats is integrated into the Sandstorm installer so that when you install
Sandstorm, you get working DNS, including wildcard DNS, as well as working HTTPS
for the main Sandstorm interface.

The Sandcats backend is free, open source software under the Apache License 2.0;
you can view and participate in the project.

The Sandcats DNS service provides 60-second latency for IP address updates via a
custom UDP protocol to detect address changes. To achieve this low latency, when
Sandcats integration is enabled, your Sandstorm server sends a UDP ping message
to the central Sandcats service every 60 seconds.


ADMINISTERING YOUR SANDCATS.IO SUBDOMAIN


FINDING DEBUGGING INFORMATION

By default, Sandstorm stores a log in a text file at
/opt/sandstorm/var/log/sandstorm.log. You can read it by running this command:

sudo less /opt/sandstorm/var/log/sandstorm.log


This launches a tool called less; for help using less, read this tutorial.


DISABLING THE SANDCATS SERVICE

If your Sandstorm server used to use sandcats.io but you want to transition to
your own domain name (with wildcard DNS), you can disable the sandcats-related
code in your Sandstorm install.

To do that, open your /opt/sandstorm/sandstorm.conf file in a text editor and
notice this line:

SANDCATS_BASE_DOMAIN=sandcats.io


Remove that line entirely, then save and quit your editor. Run sudo service
sandstorm restart to cause Sandstorm to notice your changes to its configuration
file.

That will disable the sandcats-related functionality in your Sandstorm server on
your system. This means your domain will stop automatically updating its IP
address.

Note that this does not delete any domains you registered. That's OK with us;
from our perspective, there's no need to email us to delete your domain.


RE-INSTALLING SANDSTORM AND KEEPING YOUR SANDCATS DOMAIN

If you have already registered a domain like example.sandcats.io as part of
installing Sandstorm, but you find yourself doing a fresh install of Sandstorm,
you can use our email-based recovery system.

You won't need any files from the old Sandstorm install. Instead, run the
Sandstorm install script (which we call install.sh) on a new server; follow the
prompts to recover a domain by typing help at the Sandcats prompts.

Overview. This process will:

 * Ask you what sandcats.io subdomain you use.

 * Send you an email with a short-term token.

 * Ask you for the token, then pass it to the sandcats.io service.

The install will continue and your new Sandstorm install will be bound to
example.sandcats.io.

Full details for those who are curious.

 * When you run the install.sh script, if you choose mode 1 for a full server,
   and you say yes to the defaults, install.sh prepares to enable sandcats.io
   (even if you end up not using the sandcats.io service).

 * Specifically, install.sh looks for an existing client certificate on your
   system in /opt/sandstorm/var/sandcats/id_rsa.private.combined. sandcats.io
   uses client certificates to identify a Sandstorm server as controlling a
   specific domain like example.sandcats.io. If install.sh does not find one, it
   generates one using openssl.

 * install.sh asks via the console what sandcats domain you want to register. At
   this point, you can type help. This changes the question - install.sh now
   asks what domain you want to recover. Provide your sandcats hostname.

 * install.sh then uses curl to ask sandcats.io to send an email to the address
   that you provided when first registering the domain. The email contains a
   small bit of text that serves as a one-time-use recovery token.

 * install.sh waits for you to receive the email and asks via the console for
   your recovery token.

 * install.sh sends that recovery token to sandcats.io using curl, while also
   providing the client certificate currently on your system
   (/opt/sandstorm/var/sandcats). If the recovery token matches what the server
   expects, then the server updates your user registration to trust the client
   certificate on your system.


MANUALLY MOVING SANDCATS CLIENT CERTIFICATES TO A NEW SANDSTORM INSTALL

If you prefer, you can move your sandcats.io credentials to a new Sandstorm
install without running the install.sh script. We call that file-based recovery.
Here are the steps.

 * Find your three three id_rsa certificate files (usually
   /opt/sandstorm/var/sandcats) and keep them safe somewhere. Also keep a copy
   of /opt/sandstorm/var/sandcats/https if it exists.

 * Do a new Sandstorm install, presumably on a new server somewhere. It will
   install to /opt/sandstorm. You should choose a non-sandcats.io host name
   during this process, such as using literally example.com.

 * Copy those three id_rsa certificate files from the old server to the new
   server's Sandcats directory, /opt/sandstorm/var/sandcats. Do the same for
   /opt/sandstorm/var/sandcats/https if you backed it up.

 * In your new Sandstorm install, ensure you have your BASE_URL and
   WILDCARD_HOST set properly. If your sandcats.io subdomain is example, then
   you'll need BASE_URL=example.sandcats.io and
   WILDCARD_HOST=*.example.sandcats.io. Consider copying these values from the
   old server's sandstorm.conf.

 * Edit the new server's sandstorm.conf to contain this line:
   SANDCATS_BASE_DOMAIN=sandcats.io

 * Now restart Sandstorm by running sudo service sandstorm stop ; sudo service
   sandstorm start, and wait at least 60 seconds.

 * Your DNS hostname should have auto-updated. Check that DNS is working with
   nslookup <myname>.sandcats.io from another machine. This will help eliminate
   DNS as an issue when trying to access your server.


DIAGNOSING "NOT AUTHORIZED" PROBLEMS

If you see Not Authorized in your log files, the sandcats.io service is
returning HTTP code 403 for at least one request from your server.

One reason this occurs is if you have the wrong id_rsa* certificate files in
/opt/sandstorm/var/sandcats. You can fix this problem using the email-based
recovery system; for now, this requires using install.sh on a throwaway VM. Once
your new certificate files are registered with sandcats.io, you can move them to
whichever server you want using file-based recovery.

Another reason you might see Not Authorized in the log files is if your server
has run afoul of sandcats.io's defense in depth against Sandstorm bugs.

In either case, if you need further help, please email support@sandstorm.io!


TERMS OF SERVICE, PRIVACY POLICY, & CONTACT INFORMATION

Sandcats.io has the following formal documents:

 * Sandcats.io privacy policy
 * Sandcats.io terms of service

If you have more questions, or are having trouble, email:

support@sandstorm.io

Next Previous

--------------------------------------------------------------------------------


Built with MkDocs using a theme provided by Read the Docs.
Need help?Sandstorm-dev Group IRC
GitHub « Previous Next »