Referência da linha de comando
Nesta página 14 seções
- Antes de começar
- Sintaxe
- Visão geral rápida
- Autenticação
- --authtoken
- --ephemeral-token
- Gerenciamento de serviço
- Modo headless
- --headless
- --authtoken-file
- --check-config
- O log headless
- Seleção de rede
- --network
- --net e --ip
- Proxy de saída
- --proxy
- --proxy-user
- Variáveis de ambiente de proxy
- --http-transport
- Terminal de dispositivo
- --terminal
- --terminal-user
- --pairing-key
- localtonet ssh
- Diagnósticos e informações
- --debug
- --version
- --help
- Variáveis de ambiente
- Códigos de saída
- Exemplos
- 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 #
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-usere--http-transportsó 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.
localtonetVisão geral rápida #
| Opção | Finalidade |
|---|---|
--authtoken <TOKEN> | Entra com um AuthToken. |
--ephemeral-token | Não salva o token neste dispositivo. |
--install-service, --start-service, --stop-service, --status-service, --remove-service | Gerencia o serviço em segundo plano. |
--headless | Executa sem prompts e com linhas de log simples. |
--authtoken-file <PATH> | Lê o token de um arquivo (modo headless). |
--check-config | Verifica a origem do token e sai (modo headless). |
--network | Lista 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. |
--debug | Imprime diagnósticos de conexão. |
--version | Imprime a versão. |
--help, -h | Imprime a ajuda integrada. |
Autenticação #
--authtoken #
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
--authtokene sem um token salvo, o cliente perguntaPlease 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 #
localtonet --authtoken <YOUR_TOKEN> --ephemeral-tokenUsa 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ção | O que faz | Exemplo |
|---|---|---|
--install-service | Instala 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-service | Inicia o serviço instalado. | localtonet --start-service --authtoken <YOUR_TOKEN> |
--stop-service | Para o serviço. | localtonet --stop-service --authtoken <YOUR_TOKEN> |
--status-service | Imprime o estado do serviço, por exemplo Running, Stopped ou NotFound. | localtonet --status-service --authtoken <YOUR_TOKEN> |
--remove-service | Para 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 #
localtonet --headless --authtoken-file /etc/localtonet/auth-tokenInicia 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:
| Origem | Observaçõ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_FILE | Variá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_TOKEN | Variá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 #
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 #
localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-configVerifica 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 #
| Linha | Significado |
|---|---|
Localtonet - headless log | O 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 #
localtonet --networkLista 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:
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 #
localtonet --authtoken <YOUR_TOKEN> --net Ethernet --ip 192.168.1.20Fixa 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
sudosem senha para o comandoip.
| Mensagem | Significado |
|---|---|
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 #
| Valor | O que faz |
|---|---|
Não informado, ou none | Conecta diretamente. As variáveis de ambiente de proxy são ignoradas. |
env | Usa 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 proxy | Usa esse proxy para tudo. Esquemas aceitos: http://, https://, socks5:// e socks5h://. |
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| Esquema | Comportamento | Porta padrão | Autenticação |
|---|---|---|---|
http:// | Proxy HTTP, usando CONNECT. | 80 | Nenhuma ou Basic |
https:// | Abre primeiro uma conexão TLS verificada com o proxy e depois usa CONNECT. | 443 | Nenhuma ou Basic |
socks5:// | SOCKS5, TCP e UDP. Os nomes de host são resolvidos no seu dispositivo. | 1080 | Nenhuma ou nome de usuário e senha |
socks5h:// | SOCKS5, TCP e UDP. Os nomes de host são resolvidos pelo proxy. | 1080 | Nenhuma 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 #
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 envou 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 envcom uma URL de proxy que as contenha. --install-servicerecusa--proxy-usere URLs de proxy com senha, porque um serviço não consegue armazená-las. Instale o serviço com--proxy enve 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ão | Variáveis, em ordem |
|---|---|
| HTTP e WebSocket | http_proxy, HTTP_PROXY, all_proxy, ALL_PROXY |
| HTTPS e WebSocket seguro | https_proxy, HTTPS_PROXY, all_proxy, ALL_PROXY |
| TCP e UDP brutos | all_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_proxynão tem efeito quando você passa uma URL de proxy ou conecta diretamente.
--http-transport #
localtonet --authtoken <YOUR_TOKEN> --proxy http://proxy.example.com:3128 --http-transport httpsControla 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.
| Valor | O 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. |
https | Exige o transporte HTTPS para as conexões com o servidor. |
raw | Nunca 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 #
localtonet --terminal enable --authtoken <YOUR_TOKEN>
localtonet --terminal status --authtoken <YOUR_TOKEN>
localtonet --terminal disable --authtoken <YOUR_TOKEN>| Valor | O que faz |
|---|---|
enable | Pareia 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>. |
disable | Desativa 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. |
status | Imprime 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 #
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 #
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 #
localtonet ssh <DEVICE>
localtonet ssh <DEVICE> -- uptime
localtonet ssh <DEVICE> --key <ACCESS_KEY> -- uptimeAbre 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.
| Parte | O 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. |
--stdio | Nã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 #
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 #
localtonet --versionImprime a versão do cliente, por exemplo v8.6, e sai.
--help #
localtonet --helpImprime a ajuda integrada e sai. -h faz o mesmo.
Variáveis de ambiente #
| Variável | Efeito |
|---|---|
LOCALTONET_HEADLESS | 1 ativa o modo headless. |
LOCALTONET_AUTH_TOKEN | O token, no modo headless. |
LOCALTONET_AUTH_TOKEN_FILE | Caminho de um arquivo de token, no modo headless. |
http_proxy, https_proxy, all_proxy, no_proxy e suas formas em maiúsculas | Configurações de proxy, somente com --proxy env. |
Códigos de saída #
| Código | Significado |
|---|---|
0 | O comando terminou normalmente. |
1 | Um 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. |
2 | Uma 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 #
localtonet --authtoken <YOUR_TOKEN>sudo localtonet --install-service --authtoken <YOUR_TOKEN>
sudo localtonet --status-service --authtoken <YOUR_TOKEN>docker run -d --restart unless-stopped -e LOCALTONET_AUTH_TOKEN=<YOUR_TOKEN> localtonet/localtonetlocaltonet --network
localtonet --authtoken <YOUR_TOKEN> --net Mobile --ip 10.20.30.40export all_proxy=http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy env