Serving web content from your agent through the port proxy
Services inside your agent are not reachable from outside it. scion expose
registers a local port with the Hub, which then serves it at a URL that
people with access to your agent can open.
The link serves web protocols only (HTTP, and WebSockets where supported; see
below). For a non-HTTP port (a database, a debugger, SSH or another TCP
service), the person uses scion tunnel instead, and the port must stay
exposed (see Full apps: scion tunnel).
Steps
- Run the service on
127.0.0.1 on a free port (1024 or above; 9810 and
18380 cannot be exposed). Only loopback services can be exposed.
- Run:
scion expose <port> --label "<what it is>"
- Check it works the way the person will use it (see What the proxy
carries; for pages, references/web-apps.md).
- Give the person the URL exactly as printed, including the trailing
/. Do not hand out tokens, and do not build the URL by hand.
Commands
scion expose <port> --label "<what it is>" exposes a port and prints its
URL. Exposing a port that is already exposed succeeds and prints the same
URL; it does not change the label (unexpose and expose again to relabel).
scion expose --list lists your exposed ports with their labels and URLs,
and whether auto-expose is on.
scion unexpose <port> stops exposing a port. It succeeds if the port was
not exposed. If auto-expose is on, a port that is still listening may be
exposed again on its next scan.
- An agent can have at most 10 ports exposed at once. Unexpose ports you no
longer need.
- These commands work only inside an agent with a Hub connection.
What the proxy carries
- HTTP requests of any method, with the path below the URL and the query
string passed through to your service. Programs such as scripts and
curl
can call the URL too, with the Hub credentials of someone who has access to
the agent.
- Your service does not learn who is calling. Do not build a login on top
of the link.
- WebSockets and streamed responses (for example server-sent events) work
only when the Hub runs its conduit transport, the same setting
scion tunnel needs. Without it, a WebSocket request is refused with an
error, each response is delivered whole once your service has finished
it, and request bodies are limited to 32 MiB.
- Your service must start answering within 60 seconds (the Hub's default),
or the caller gets a timeout error. Without the conduit transport, the
whole response must arrive within that time.
- What a page opened in a browser through the link can load depends on the
Hub: with its page view on, the page's relative URLs load; with it off, the
page can only use what is inside it. See references/web-apps.md before
serving a web page or app.
Full apps: scion tunnel
For a full multi-file web app, a dev server, or anything the proxy does not
carry, the person can run scion tunnel on their own machine with the scion
CLI, if their Hub has scion tunnel turned on and they have port access to
the agent. Keep the port exposed with scion expose <port> (the tunnel only
reaches exposed ports), then suggest:
scion tunnel <agent> --port <port>
The service then opens on a local port on their machine and works as it does
inside the agent, for any protocol. See
https://googlecloudplatform.github.io/scion/hosted/user/port-forwarding/
Web pages and apps
For anything a person opens in a browser through the link, read
references/web-apps.md: what loads with and without the Hub's page view,
build settings, what does not work in a page, routing, and how to verify it
honestly.
1---2name: scion-web-serving3description: >-4 How to serve a web page, app, API or other HTTP service from inside your5 agent so a person or program can reach it through the Hub's port proxy:6 scion expose and unexpose, the URL to hand over, what the proxy carries,7 and scion tunnel for full apps. The link serves web protocols only; for a8 non-HTTP port, point the person to scion tunnel. Use before running scion9 expose. For web pages and apps, also read references/web-apps.md.10metadata:11 source: https://skillmd.com/skills/googlecloudplatform/scion-web-serving12---1314# Serving web content from your agent through the port proxy1516Services inside your agent are not reachable from outside it. `scion expose`17registers a local port with the Hub, which then serves it at a URL that18people with access to your agent can open.1920The link serves web protocols only (HTTP, and WebSockets where supported; see21below). For a non-HTTP port (a database, a debugger, SSH or another TCP22service), the person uses `scion tunnel` instead, and the port must stay23exposed (see Full apps: scion tunnel).2425## Steps26271. Run the service on `127.0.0.1` on a free port (1024 or above; 9810 and28 18380 cannot be exposed). Only loopback services can be exposed.292. Run: `scion expose <port> --label "<what it is>"`303. Check it works the way the person will use it (see What the proxy31 carries; for pages, references/web-apps.md).324. Give the person the URL **exactly as printed**, including the trailing33 `/`. Do not hand out tokens, and do not build the URL by hand.3435## Commands3637- `scion expose <port> --label "<what it is>"` exposes a port and prints its38 URL. Exposing a port that is already exposed succeeds and prints the same39 URL; it does not change the label (unexpose and expose again to relabel).40- `scion expose --list` lists your exposed ports with their labels and URLs,41 and whether auto-expose is on.42- `scion unexpose <port>` stops exposing a port. It succeeds if the port was43 not exposed. If auto-expose is on, a port that is still listening may be44 exposed again on its next scan.45- An agent can have at most 10 ports exposed at once. Unexpose ports you no46 longer need.47- These commands work only inside an agent with a Hub connection.4849## What the proxy carries5051- HTTP requests of any method, with the path below the URL and the query52 string passed through to your service. Programs such as scripts and `curl`53 can call the URL too, with the Hub credentials of someone who has access to54 the agent.55- Your service does not learn who is calling. Do not build a login on top56 of the link.57- WebSockets and streamed responses (for example server-sent events) work58 only when the Hub runs its conduit transport, the same setting59 `scion tunnel` needs. Without it, a WebSocket request is refused with an60 error, each response is delivered whole once your service has finished61 it, and request bodies are limited to 32 MiB.62- Your service must start answering within 60 seconds (the Hub's default),63 or the caller gets a timeout error. Without the conduit transport, the64 whole response must arrive within that time.65- What a page opened in a browser through the link can load depends on the66 Hub: with its page view on, the page's relative URLs load; with it off, the67 page can only use what is inside it. See references/web-apps.md before68 serving a web page or app.6970## Full apps: scion tunnel7172For a full multi-file web app, a dev server, or anything the proxy does not73carry, the person can run `scion tunnel` on their own machine with the scion74CLI, if their Hub has `scion tunnel` turned on and they have port access to75the agent. Keep the port exposed with `scion expose <port>` (the tunnel only76reaches exposed ports), then suggest:7778 scion tunnel <agent> --port <port>7980The service then opens on a local port on their machine and works as it does81inside the agent, for any protocol. See82https://googlecloudplatform.github.io/scion/hosted/user/port-forwarding/8384## Web pages and apps8586For anything a person opens in a browser through the link, read87references/web-apps.md: what loads with and without the Hub's page view,88build settings, what does not work in a page, routing, and how to verify it89honestly.