Ir para o conteúdo
Localtonet Localtonet Painel

Referência da linha de comando

Ajuda com esta página
Nesta página 14 seções
  1. Antes de começar
  2. Sintaxe
  3. Visão geral rápida
  4. Autenticação
  5. --authtoken
  6. --ephemeral-token
  7. Gerenciamento de serviço
  8. Modo headless
  9. --headless
  10. --authtoken-file
  11. --check-config
  12. O log headless
  13. Seleção de rede
  14. --network
  15. --net e --ip
  16. Proxy de saída
  17. --proxy
  18. --proxy-user
  19. Variáveis de ambiente de proxy
  20. --http-transport
  21. Terminal de dispositivo
  22. --terminal
  23. --terminal-user
  24. --pairing-key
  25. localtonet ssh
  26. Diagnósticos e informações
  27. --debug
  28. --version
  29. --help
  30. Variáveis de ambiente
  31. Códigos de saída
  32. Exemplos
  33. Páginas relacionadas

Todas as opções do cliente de console localtonet: entrar com um token, executar como serviço, executar sem prompts, escolher uma rede ou um proxy de saída e os comandos do Terminal de dispositivo.

Antes de começar #

Esta página trata do cliente de console para Windows, macOS e Linux, incluindo o cliente dentro da imagem Docker e dos pacotes Linux. Instale-o pela visão geral de instalação. Os túneis não são criados na linha de comando: você os cria, inicia e para no painel, com a API ou com o servidor MCP. O cliente conecta um dispositivo à sua conta e transporta o tráfego.

Sintaxe #

Bash
localtonet [options]
localtonet ssh <DEVICE> [--key <KEY>] [--stdio] [-- <COMMAND>]
  • As opções podem ser informadas em qualquer ordem. Os nomes das opções não diferenciam maiúsculas de minúsculas, exceto as opções de localtonet ssh.
  • O valor vem depois da opção, separado por um espaço ou por um sinal de igual: --authtoken <YOUR_TOKEN> e --authtoken=<YOUR_TOKEN> são equivalentes.
  • Uma opção que precisa de um valor falha com <option> requires a value. quando o valor está ausente.
  • --proxy, --proxy-user e --http-transport só podem ser informadas uma vez.
  • Marcadores como <YOUR_TOKEN> representam os seus próprios valores. Digite-os sem os sinais de menor e maior.

Sem opções, o cliente inicia no modo interativo: usa o token salvo ou pede um, conecta e mostra uma tabela de status ao vivo.

Bash
localtonet

Visão geral rápida #

OpçãoFinalidade
--authtoken <TOKEN>Entra com um AuthToken.
--ephemeral-tokenNão salva o token neste dispositivo.
--install-service, --start-service, --stop-service, --status-service, --remove-serviceGerencia o serviço em segundo plano.
--headlessExecuta sem prompts e com linhas de log simples.
--authtoken-file <PATH>Lê o token de um arquivo (modo headless).
--check-configVerifica a origem do token e sai (modo headless).
--networkLista as interfaces de rede do dispositivo.
--net <NAME> --ip <ADDRESS>Envia todo o tráfego do cliente por uma única interface de rede.
--proxy <none|env|URL>, --proxy-user <USER>Conecta-se ao Localtonet por um proxy de saída.
--http-transport <auto|https|raw>Escolhe como as conexões com o servidor passam por um proxy.
--terminal <enable|disable|status>, --terminal-user <ACCOUNT>, --pairing-key <KEY>Ativa ou desativa o Terminal de dispositivo neste dispositivo.
ssh <DEVICE>Abre um shell ou executa um comando em um dos seus dispositivos.
--debugImprime diagnósticos de conexão.
--versionImprime a versão.
--help, -hImprime a ajuda integrada.

Autenticação #

--authtoken #

Bash
localtonet --authtoken <YOUR_TOKEN>

Faz login do dispositivo com um AuthToken de Meus tokens. Um token tem 33 caracteres. O cliente o salva no perfil do usuário atual, então na próxima vez basta um localtonet simples.

  • Sem --authtoken e sem um token salvo, o cliente pergunta Please Enter AuthToken or PIN. Você pode digitar o token ou um PIN de seis dígitos que o painel mostra para um token.
  • Um valor que não é um token válido recebe a resposta Wrong Token! e a pergunta é feita de novo.
  • Enquanto o cliente está em execução, F12 remove o token salvo e encerra. Ctrl + C encerra e o mantém.
  • A grafia antiga, sem os traços, authtoken <YOUR_TOKEN>, ainda é aceita.

Mantenha o seu token privado. Ele permite que o cliente Localtonet se conecte como este dispositivo. Use um token por dispositivo: um segundo cliente que se conecte com o mesmo token desconecta o primeiro.

--ephemeral-token #

Bash
localtonet --authtoken <YOUR_TOKEN> --ephemeral-token

Usa o token apenas nesta execução. O cliente não grava o token nas configurações salvas e não altera um token que já esteja salvo. Use para automação e sessões temporárias.

Gerenciamento de serviço #

Estas opções registram o cliente nos serviços do Windows, no launchd do macOS ou no systemd do Linux. Elas exigem direitos de administrador (sudo no macOS e no Linux), e cada uma precisa do token, porque o serviço recebe o nome dele. O guia completo é Executar como serviço.

OpçãoO que fazExemplo
--install-serviceInstala o cliente como um serviço que inicia com o sistema e o inicia. As demais opções da linha de comando ficam armazenadas no serviço.localtonet --install-service --authtoken <YOUR_TOKEN>
--start-serviceInicia o serviço instalado.localtonet --start-service --authtoken <YOUR_TOKEN>
--stop-servicePara o serviço.localtonet --stop-service --authtoken <YOUR_TOKEN>
--status-serviceImprime o estado do serviço, por exemplo Running, Stopped ou NotFound.localtonet --status-service --authtoken <YOUR_TOKEN>
--remove-servicePara o serviço e o remove.localtonet --remove-service --authtoken <YOUR_TOKEN>

As opções de serviço não são usadas no modo headless.

Modo headless #

O modo headless é para contêineres, sistemas init e scripts. O cliente nunca faz perguntas, não reage a teclas, não salva o token e escreve uma linha de log simples por alteração, em vez da tabela de status. A imagem Docker e os pacotes Linux e OpenWrt executam o cliente assim.

--headless #

Bash
localtonet --headless --authtoken-file /etc/localtonet/auth-token

Inicia o cliente no modo headless. Definir a variável de ambiente LOCALTONET_HEADLESS=1 tem o mesmo efeito. O cliente é encerrado de forma limpa ao receber um sinal de término.

O token vem de uma destas origens:

OrigemObservações
--authtoken-file <PATH>Um arquivo que contém apenas o token. Espaços e quebras de linha ao redor são ignorados.
LOCALTONET_AUTH_TOKEN_FILEVariável de ambiente com o caminho de um arquivo desse tipo. Usada quando --authtoken-file não é informada.
--authtoken <TOKEN>O próprio token na linha de comando.
LOCALTONET_AUTH_TOKENVariável de ambiente com o token. Usada quando --authtoken não é informada.

Um arquivo de token sempre tem prioridade sobre um token passado diretamente. Se um arquivo de token é indicado mas não pode ser lido, o cliente é encerrado; ele não recorre a outra origem.

Quando nenhum token utilizável é encontrado, o cliente imprime Invalid Localtonet headless configuration. Check the token file or environment settings. e sai com o código 2. Um token utilizável tem 33 caracteres e não contém espaços.

--authtoken-file #

Bash
localtonet --headless --authtoken-file <PATH>

Lê o token de um arquivo em vez da linha de comando, para que ele não apareça nas listas de processos nem no histórico do shell. Proteja o arquivo, por exemplo com chmod 600. Esta opção só é lida no modo headless.

--check-config #

Bash
localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config

Verifica a origem do token e sai sem conectar. Imprime Localtonet headless configuration OK. e sai com o código 0 quando um token bem formado foi encontrado; caso contrário, imprime o erro acima e sai com o código 2. A verificação é local: ela não informa se o Localtonet aceita o token. Combine-a sempre com --headless (ou LOCALTONET_HEADLESS=1); sozinha, ela é ignorada.

O log headless #

LinhaSignificado
Localtonet - headless logO cliente foi iniciado.
Connection: …O estado da conexão mudou.
AuthTokenName: …O nome do token com o qual o dispositivo fez login.
OPEN …, ADDED …Um túnel que já existia na inicialização ou que foi adicionado depois.
STATUS …Um túnel mudou de status.
CLOSED …Um túnel foi removido deste cliente.
Authentication failed: AuthToken was rejected.O Localtonet não aceitou o token.

Toda linha depois da primeira começa com um carimbo de data e hora. O token nunca é escrito no log.

Seleção de rede #

Em um dispositivo com mais de uma conexão de internet, por exemplo Ethernet e um modem móvel, você pode escolher qual delas o cliente usa. A página Seleção de rede explica o recurso e a configuração por túnel.

--network #

Bash
localtonet --network

Lista todas as interfaces de rede ativas com seus endereços, verifica se cada endereço IPv4 alcança a internet e sai. Cada linha já vem escrita como as opções que você passaria:

Saída
NetworkName: Ethernet
--net Ethernet --ip 192.168.1.20   --> Internet available (public IP 203.0.113.10)
--------------------------------------------------
NetworkName: Mobile
--net Mobile --ip 10.20.30.40   --> No internet access
--------------------------------------------------

Os endereços IPv6 são listados com IPv6, internet check not available.

--net e --ip #

Bash
localtonet --authtoken <YOUR_TOKEN> --net Ethernet --ip 192.168.1.20

Fixa o cliente inteiro em uma única interface de rede. --net é o nome da interface e --ip é um endereço dessa interface, exatamente como --network os imprime. As duas devem ser informadas juntas. Um nome de interface com espaços pode ser escrito como está ou entre aspas.

  • Se o par não puder ser aplicado, o cliente espera até 30 segundos para a interface ficar ativa, o que ajuda quando ele inicia junto com o sistema, e então para com o motivo e o código de saída 2. Ele não continua em outra rede.
  • Se apenas uma das duas opções for informada, o cliente imprime --net and --ip must be given together; the default network is used. e continua sem fixação.
  • No Linux, o cliente adiciona regras de roteamento para o endereço fixado. Isso exige root, ou sudo sem senha para o comando ip.
MensagemSignificado
Network interface '…' was not found. Run 'localtonet --network' to list the interfaces.O nome após --net não corresponde a nenhuma interface.
Network interface '…' is Down.A interface existe, mas não está ativa.
'…' is not an address of network interface '…'.O endereço após --ip não pertence a essa interface.
'…' is not an IP address.O valor após --ip não é um endereço IP.

Para usar uma conexão diferente em um único túnel, em vez do cliente inteiro, defina o mesmo par na configuração Argumentos desse túnel.

Proxy de saída #

Use estas opções quando o dispositivo só puder acessar a internet por um proxy. Elas se aplicam às conexões do próprio cliente com o Localtonet. Não mudam a forma como o cliente alcança o seu serviço local.

--proxy #

ValorO que faz
Não informado, ou noneConecta diretamente. As variáveis de ambiente de proxy são ignoradas.
envUsa as variáveis de ambiente de proxy descritas abaixo. Se nenhuma estiver definida, ou se alguma for inválida, o cliente para com um erro em vez de conectar diretamente.
Uma URL de proxyUsa esse proxy para tudo. Esquemas aceitos: http://, https://, socks5:// e socks5h://.
Bash
localtonet --authtoken <YOUR_TOKEN> --proxy http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy socks5h://proxy.example.com:1080
localtonet --authtoken <YOUR_TOKEN> --proxy env
EsquemaComportamentoPorta padrãoAutenticação
http://Proxy HTTP, usando CONNECT.80Nenhuma ou Basic
https://Abre primeiro uma conexão TLS verificada com o proxy e depois usa CONNECT.443Nenhuma ou Basic
socks5://SOCKS5, TCP e UDP. Os nomes de host são resolvidos no seu dispositivo.1080Nenhuma ou nome de usuário e senha
socks5h://SOCKS5, TCP e UDP. Os nomes de host são resolvidos pelo proxy.1080Nenhuma ou nome de usuário e senha

O host do proxy pode ser um endereço IPv4, um nome de host ou um endereço IPv6 entre colchetes. As credenciais podem fazer parte da URL como user:password@host:port; codifique em URL os caracteres especiais nelas. A saída de depuração nunca inclui credenciais.

--proxy-user #

Bash
localtonet --authtoken <YOUR_TOKEN> --proxy socks5h://proxy.example.com:1080 --proxy-user <PROXY_USER>

Define o nome de usuário do proxy e pede a senha em um prompt oculto (Proxy password:), para que a senha não fique na linha de comando. A senha não é salva.

  • Ela exige --proxy env ou uma URL de proxy e não pode ser combinada com credenciais dentro da URL.
  • Só funciona em um terminal interativo. O modo headless e os serviços nunca fazem perguntas: coloque as credenciais na URL do proxy ou use --proxy env com uma URL de proxy que as contenha.
  • --install-service recusa --proxy-user e URLs de proxy com senha, porque um serviço não consegue armazená-las. Instale o serviço com --proxy env e forneça as variáveis no ambiente do serviço.

Variáveis de ambiente de proxy #

Elas só são lidas com --proxy env. Para cada tipo de conexão, é usada a primeira variável definida:

ConexãoVariáveis, em ordem
HTTP e WebSockethttp_proxy, HTTP_PROXY, all_proxy, ALL_PROXY
HTTPS e WebSocket segurohttps_proxy, HTTPS_PROXY, all_proxy, ALL_PROXY
TCP e UDP brutosall_proxy, ALL_PROXY, https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY

no_proxy (ou NO_PROXY, se a de minúsculas não estiver definida) lista os hosts que são acessados diretamente:

  • As entradas são separadas por vírgulas. Um host ou domínio corresponde a ele mesmo e aos seus subdomínios. A comparação ignora maiúsculas e minúsculas e um ponto inicial.
  • Os endereços IP correspondem exatamente; os endereços IPv6 podem estar entre colchetes. * ignora o proxy para todos os hosts.
  • Intervalos de endereços (CIDR), entradas com porta e curingas parciais não são aceitos e são relatados como erro de configuração.
  • no_proxy não tem efeito quando você passa uma URL de proxy ou conecta diretamente.

--http-transport #

Bash
localtonet --authtoken <YOUR_TOKEN> --proxy http://proxy.example.com:3128 --http-transport https

Controla como o cliente transporta as conexões com o servidor quando um proxy só deixa passar tráfego web comum. Com o transporte HTTPS, o cliente envia esse tráfego como requisições HTTPS normais a um gateway do Localtonet, em vez de abrir conexões brutas de longa duração pelo proxy.

ValorO que faz
auto (padrão)Atrás de um proxy HTTP ou HTTPS, o cliente prefere o transporte HTTPS quando o servidor o oferece e, caso contrário, usa CONNECT. Atrás de um proxy SOCKS5, usa primeiro TCP e UDP nativos e pode recorrer ao transporte HTTPS pelo mesmo proxy.
httpsExige o transporte HTTPS para as conexões com o servidor.
rawNunca usa o transporte HTTPS: apenas CONNECT ou SOCKS.

Qualquer outro valor faz o cliente parar com LOCALTONET_HTTP_TRANSPORT_MODE must be auto, https or raw.

Terminal de dispositivo #

O Terminal de dispositivo dá a você um shell nos seus próprios dispositivos, a partir do painel ou por SSH. Ele funciona no Windows, no Linux e no macOS e exige o Localtonet Desktop v8.6 ou posterior. A página Terminal de dispositivo descreve o recurso; estas são as partes dele na linha de comando.

--terminal #

Bash
localtonet --terminal enable --authtoken <YOUR_TOKEN>
localtonet --terminal status --authtoken <YOUR_TOKEN>
localtonet --terminal disable --authtoken <YOUR_TOKEN>
ValorO que faz
enablePareia este dispositivo com a sua conta. O comando imprime um código de aprovação e espera; abra Meus dispositivos, selecione Adicionar dispositivo e digite o código. O código é válido por 15 minutos. Após a aprovação, o comando imprime Terminal enabled. Shells will run as <account>.
disableDesativa o terminal neste dispositivo e remove o dispositivo da sua conta. Se o painel não puder ser alcançado, o terminal ainda é desativado localmente e o comando pede que você remova o dispositivo também no painel.
statusImprime se o terminal está ativado e como qual conta os shells são executados.

As três formas precisam de um token, como uma inicialização normal: passe --authtoken ou omita-o para usar o token salvo. Se o Localtonet é executado como serviço no dispositivo, execute o comando em um terminal de Administrador ou com sudo. Em um terminal interativo, o cliente continua em execução como um cliente normal depois de enable, a menos que o Localtonet já esteja em execução no dispositivo com este token.

--terminal-user #

Bash
sudo localtonet --terminal enable --authtoken <YOUR_TOKEN> --terminal-user <ACCOUNT>

Escolhe a conta como a qual os shells são executados, quando você ativa o terminal como root ou como administrador. Sem ela, um enable elevado pergunta Run shells as user:; em um script, onde nada pode ser perguntado, ele para com Choose the account for shells with --terminal-user. Sem --terminal-user, um comando que não é elevado usa o usuário atual.

--pairing-key #

Bash
localtonet --terminal enable --authtoken <YOUR_TOKEN> --terminal-user <ACCOUNT> --pairing-key <PAIRING_KEY>

Pareia um dispositivo em que ninguém consegue ler um código de aprovação, por exemplo um servidor que você configura com um script. Crie a chave em Meus dispositivos, em Adicionar dispositivo, com Criar chave de uso único. Ela é válida por uma hora e pode ser usada uma vez. Com uma chave de pareamento, o comando não imprime um código e não espera aprovação.

localtonet ssh #

Bash
localtonet ssh <DEVICE>
localtonet ssh <DEVICE> -- uptime
localtonet ssh <DEVICE> --key <ACCESS_KEY> -- uptime

Abre um shell em um dos seus dispositivos ou executa um comando nele e devolve o código de saída. <DEVICE> é o nome do dispositivo mostrado em Meus dispositivos. ssh deve ser a primeira palavra depois de localtonet.

ParteO que faz
-- <COMMAND>Executa o comando em vez de abrir um shell. Tudo o que vem depois de -- é o comando.
--key <ACCESS_KEY>Uma chave de acesso do dispositivo, criada em Chaves em Meus dispositivos. Com uma chave, nenhuma aprovação no navegador é necessária.
--stdioNão abre um shell. Apenas transporta a conexão bruta até o dispositivo pela entrada e saída padrão, para uso como ProxyCommand de um cliente SSH.

Sem uma chave, o comando imprime Approve this connection in your browser: seguido de um link e espera até cinco minutos para você aprovar. Se a conexão não for aprovada, ele termina com The connection was not approved.

Diagnósticos e informações #

--debug #

Bash
localtonet --debug --proxy env --authtoken <YOUR_TOKEN>

Ativa os diagnósticos de conexão na saída de erro padrão: as rotas de proxy em uso e de qual configuração vêm, o modo DNS, os resultados do handshake e o status do UDP. Credenciais e corpos de requisição ficam de fora. --debug também coloca o cliente no modo headless, então ele não faz perguntas. É um flag e não recebe valor.

--version #

Bash
localtonet --version

Imprime a versão do cliente, por exemplo v8.6, e sai.

--help #

Bash
localtonet --help

Imprime a ajuda integrada e sai. -h faz o mesmo.

Variáveis de ambiente #

VariávelEfeito
LOCALTONET_HEADLESS1 ativa o modo headless.
LOCALTONET_AUTH_TOKENO token, no modo headless.
LOCALTONET_AUTH_TOKEN_FILECaminho de um arquivo de token, no modo headless.
http_proxy, https_proxy, all_proxy, no_proxy e suas formas em maiúsculasConfigurações de proxy, somente com --proxy env.

Códigos de saída #

CódigoSignificado
0O comando terminou normalmente.
1Um comando do Terminal de dispositivo falhou, por exemplo porque o código de aprovação expirou ou o dispositivo não pôde ser alcançado.
2Uma opção está errada ou sem valor, o token headless é inutilizável, ou o par --net e --ip não pôde ser aplicado.

localtonet ssh <DEVICE> -- <COMMAND> devolve o código de saída do comando remoto.

Exemplos #

Primeira inicialização em um desktop
localtonet --authtoken <YOUR_TOKEN>
Serviço em segundo plano no Linux
sudo localtonet --install-service --authtoken <YOUR_TOKEN>
sudo localtonet --status-service --authtoken <YOUR_TOKEN>
Docker, token vindo do ambiente
docker run -d --restart unless-stopped -e LOCALTONET_AUTH_TOKEN=<YOUR_TOKEN> localtonet/localtonet
Usar o modem móvel para tudo
localtonet --network
localtonet --authtoken <YOUR_TOKEN> --net Mobile --ip 10.20.30.40
Atrás de um proxy corporativo
export all_proxy=http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy env
Suporte