Documentação · Uso
Comandos
Referência de todos os comandos do osx-reims e das suas opções.
Esta documentação corresponde ao OSX-REIMS 0.6.0, em estágio alfa. Comandos e opções podem mudar entre versões; na dúvida, confira osx-reims --help na versão instalada.
Sem comando, osx-reims abre o console. Tudo o que o menu faz também existe como comando, para quem prefere o terminal ou quer automatizar.
osx-reims [comando] [opções]Resumo
| Comando | O que faz |
|---|---|
setup |
Prepara o computador: pacotes, KVM, acesso à GPU, Rust e Reims vGPU |
doctor |
Confere se o computador está pronto, sem mudar nada |
logs |
Lista os logs das execuções recentes e como cada uma terminou |
update [arquivo.deb] |
Instala uma versão nova do OSX-REIMS a partir de um pacote que você já baixou |
update-reims |
Atualiza o Reims vGPU para a versão testada ou a mais recente e o compila |
rebuild-reims |
Compila o Reims vGPU de novo do zero, na mesma versão |
create |
Cria uma VM pronta para instalar o macOS |
import |
Cria uma VM a partir do disco QCOW2 de um macOS já instalado em outra VM |
list |
Lista as VMs, o estado de cada uma e as que estão rodando |
start [VM] |
Inicia a VM; sem número, pergunta qual |
stop [VM] |
Pede ao macOS para desligar e espera |
reset [VM] |
Reinicia a VM à força |
poweroff [VM] |
Desliga a VM à força, como tirar da tomada (também quit) |
term [VM] |
Encerra o processo da VM, quando ela não responde |
delete [VM] |
Apaga uma VM desligada |
delete --all |
Apaga todas as VMs, que precisam estar desligadas |
backup [VM] |
Faz o backup de uma VM em um único arquivo (--list, --delete) |
restore [arquivo] |
Restaura uma VM de um backup: por cima dela ou como uma nova VM |
clean-cache [versão] |
Apaga os instaladores do macOS baixados (--all: todo o cache) |
autostart [on|off] |
Define se uma VM abre sozinha quando o computador é ligado |
network |
A rede das VMs: NAT ou a ponte que dá a elas um endereço próprio (bridge on|off) |
help |
Mostra a ajuda |
version, --version |
Mostra a versão do OSX-REIMS |
Cada comando tem a própria ajuda: osx-reims <comando> --help.
Opções comuns
| Opção | O que faz |
|---|---|
-y, --yes |
Não faz perguntas: usa os valores das opções ou os padrões |
--debug |
Inclui o rastreamento do bash (set -x) no log |
-h, --help |
Mostra a ajuda do comando |
Onde aparece [VM], use o número da VM (por exemplo, 13) ou o nome da pasta dela (macos-13). A opção -i <n> também funciona.
Cada ação grava um log em /opt/osx-reims/logs/, com a ação, a data e a hora no nome do arquivo. O mais recente também fica em latest.log.
Preparação do computador
setup
osx-reims setup [opções]Prepara o computador: pacotes do sistema, acesso à GPU, KVM, Rust e o Reims vGPU, baixado em /opt/reims-vgpu e compilado. Rode com o seu usuário normal, sem sudo: a senha de administrador só é pedida nas etapas que precisam dela. Pode ser executado de novo, porque etapas já concluídas são puladas. Veja Instalação.
| Opção | O que faz |
|---|---|
--tested |
Segue o commit testado do Reims vGPU (padrão) |
--latest |
Segue o commit mais recente do Reims vGPU, não testado |
--reims-ref <ref> |
Usa um commit, tag ou branch do Reims vGPU (avançado, não testado) |
--accept-license |
Aceita a licença sem perguntar (obrigatório com -y) |
--rebuild |
Compila o Reims vGPU de novo, mesmo que já esteja atualizado |
--skip-build |
Para antes da compilação (para testes) |
-y, --yes |
Não pergunta nada; o sudo ainda pode pedir a senha |
doctor
osx-reims doctor [opções]Confere se o computador está pronto e mostra o que está errado e como corrigir. Não muda nada e não pede senha. O log dele não tem números de série nem outros dados de identidade das VMs e é o que deve ser compartilhado ao pedir ajuda. Veja Solução de problemas.
| Opção | O que faz |
|---|---|
--online |
Também testa a conexão com o GitHub e com os servidores do Rust |
Código de saída: 0 quando nenhuma verificação falhou (avisos são permitidos) e 1 quando alguma falhou.
update-reims
osx-reims update-reims [opções]Atualiza o Reims vGPU em /opt/reims-vgpu e o compila de novo, seguindo a versão escolhida. Sem --tested ou --latest, pergunta qual seguir, oferecendo a escolha atual. Todas as VMs precisam estar desligadas. Se o novo commit não compilar ou não passar nas verificações, o commit anterior volta e é compilado de novo. Veja Versão do Reims vGPU.
| Opção | O que faz |
|---|---|
--tested |
Vai para o commit testado e passa a segui-lo |
--latest |
Vai para o commit mais recente do master e passa a segui-lo (não testado) |
--reims-ref <ref> |
Usa um commit, tag ou branch do Reims vGPU (avançado, não testado) |
-y, --yes |
Não pergunta: mantém a escolha atual, a menos que uma opção a mude |
VMs
create
osx-reims create [opções]Cria uma VM com disco vazio, OpenCore e o instalador do macOS: o Recovery, baixado da Apple (a instalação usa a internet), ou uma imagem de instalador completo. Sem opções, pergunta os valores. Cada VM recebe número de série, MLB, UUID, ROM e endereço MAC próprios. Veja Primeira VM.
| Opção | O que faz |
|---|---|
-i, --id <n> |
Número da VM, de 10 a 99 (padrão: o primeiro livre) |
-m, --macos <nome> |
ventura, sonoma, sequoia ou tahoe (padrão: ventura; com --installer, a versão da imagem) |
-s, --disk-size <n> |
Tamanho do disco do macOS, como 256G ou 1T (padrão: 256G) |
--installer <imagem> |
Usa uma imagem de instalador completo em vez do Recovery |
--redownload |
Baixa o Recovery de novo, mesmo que já esteja em cache |
Exemplo sem perguntas:
osx-reims create -i 11 -m sonoma -s 256G -yimport
osx-reims import [opções]Cria uma VM a partir do disco QCOW2 de um macOS já instalado em outra VM, como no OSX-PROXMOX, com disco de inicialização próprio. O disco é copiado para a pasta da VM: o arquivo original não é alterado e pode ser apagado depois. A VM recebe identidade nova. Sem opções, pergunta os valores. Veja Importar uma VM.
| Opção | O que faz |
|---|---|
-i, --id <n> |
Número da VM, de 10 a 99 (padrão: o primeiro livre) |
-d, --disk <arquivo> |
Disco QCOW2 a importar |
-m, --macos <nome> |
ventura, sonoma, sequoia, tahoe ou other: a versão mostrada na lista de VMs |
-y, --yes |
Não pergunta nada (exige --disk) |
Exemplo:
osx-reims import -d ~/Downloads/macos.qcow2 -m tahoelist
osx-reims list [--json]Lista as VMs, o estado de cada uma e as que estão rodando. Os estados são explicados em Primeira VM. Com --json, a mesma lista sai como um único objeto JSON, para ser lida por um programa, sem cores e sem log.
start
osx-reims start [VM] [opções]Inicia a VM. Sem número, pergunta qual; se a escolhida já estiver rodando, pergunta o que fazer com ela. Na primeira inicialização de uma VM criada com instalador, abre a instalação do macOS.
Cada configuração respondida por uma opção também passa a ser o valor salvo daquela VM. Sem opções, o start mostra o resumo do que a VM vai usar e pergunta apenas se deve iniciar, mudar uma configuração ou cancelar. Veja Configurações da VM.
| Opção | O que faz |
|---|---|
-r, --ram <n> |
Memória, como 8G ou 16384M (padrão: o valor salvo da VM, senão 8G) |
-c, --cpus <n> |
Processadores, de 1 a 32 (padrão: o valor salvo da VM, senão 4) |
--opencore <s> |
Qual OpenCore inicia a VM: image ou esp (padrão: a escolha salva da VM, senão image) |
--install-esp |
Com --opencore esp: se a EFI do disco do macOS não tiver OpenCore, instala o da VM nela antes de iniciar; um OpenCore que já está lá é usado como está |
--attach-installer |
Conecta de novo o instalador da VM nesta inicialização, para uma instalação interrompida; o disco fica como está e a próxima inicialização é sem ele |
--fullscreen |
A VM ocupa o monitor inteiro, sem o Ubuntu atrás dela |
--windowed |
A VM abre em uma janela normal (padrão dos dois: a escolha salva da VM, senão janela) |
--x11 |
A janela da VM abre no X11, pelo XWayland |
--wayland |
A janela da VM abre no Wayland da sessão (padrão dos dois: a escolha salva da VM, senão o servidor da sessão) |
--nested |
O macOS pode rodar VMs próprias (Docker, VirtualBox); precisa de um computador Intel |
--no-nested |
O macOS vê um processador sem VT-x (padrão dos dois: a escolha salva da VM, senão desligado) |
--gpu <s> |
Qual GPU roda a VM: auto ou o identificador fabricante:dispositivo, como 1002:73ff (padrão: a escolha salva da VM, senão auto) |
--refresh <s> |
A taxa de atualização do macOS: auto (a do monitor) ou uma taxa em Hz, como 120 (padrão: a escolha salva da VM, senão auto) |
--net <s> |
A rede da VM: nat ou bridge, que precisa de osx-reims network bridge on (padrão: a escolha salva da VM, senão nat) |
--audio |
A VM tem som: o do macOS e o som de inicialização do OpenCore |
--no-audio |
A VM não tem dispositivo de som (padrão dos dois: a escolha salva da VM, senão com som) |
-n, --dry-run |
Mostra o comando de inicialização e sai, sem iniciar a VM |
-y, --yes |
Não pergunta: usa as opções, depois o que está salvo na VM, depois os padrões; sem número, usa a VM atual, normalmente a última criada |
Nota
--fullscreen e --windowed, --x11 e --wayland, --nested e --no-nested, --audio e --no-audio são pares: usar os dois do mesmo par é recusado. Todas essas opções valem apenas para o start.
Com a VM aberta pelo start, o terminal aceita teclas, sempre pressionadas duas vezes em até 5 segundos:
| Tecla | O que faz |
|---|---|
S |
Pede ao macOS para desligar |
R |
Reinicia a VM à força |
F |
Desliga a VM à força |
T |
Encerra o processo da VM |
Pressionar Ctrl+C duas vezes também pede ao macOS para desligar. Fechar o terminal não desliga a VM; fechar a janela da VM a desliga na hora.
stop, reset, poweroff e term
osx-reims stop [VM] [opções]
osx-reims reset [VM] [opções]
osx-reims poweroff [VM] [opções]
osx-reims term [VM] [opções]stoppede ao macOS para desligar e espera. Se o macOS não desligar a tempo, pergunta se deve esperar mais, forçar o desligamento ou cancelar.resetreinicia a VM à força.poweroff, ouquit, desliga a VM à força, como tirar da tomada.termencerra o processo da VM, para quando ela não responde.
Atenção
Para o macOS, reset, poweroff e term equivalem a um corte de energia: o que não foi salvo se perde. O disco da VM continua íntegro nos três casos.
Sem número e com uma única VM rodando, esses comandos agem sobre ela.
| Opção | O que faz |
|---|---|
--wait <s> |
stop: segundos de espera pelo macOS (padrão: 60) |
--pid <n> |
Age sobre o processo do QEMU com esse PID (obrigatório para VMs fora da pasta de VMs) |
-y, --yes |
Não pede confirmação |
delete
osx-reims delete [VM] [opções]
osx-reims delete --all [opções]Apaga a pasta inteira da VM, com os discos. Sem número, pergunta qual. A VM precisa estar desligada; com --all, todas precisam estar, senão nenhuma é apagada. O cache de instaladores não é tocado.
Cuidado
Apagar uma VM não pode ser desfeito: o macOS instalado e todos os arquivos dentro dele são apagados.
| Opção | O que faz |
|---|---|
--all |
Apaga todas as VMs |
-y, --yes |
Não pede confirmação |
backup e restore
osx-reims backup [VM] [opções]
osx-reims backup --list [--json]
osx-reims backup --delete [arquivo] [opções]
osx-reims restore [arquivo] [opções]backup guarda a pasta inteira da VM — disco do macOS, disco de inicialização, configurações do firmware, identidade e configurações — em um único arquivo em /opt/osx-reims/backup. A VM precisa estar desligada enquanto é copiada; uma VM ligada é desligada antes, se você concordar. restore coloca um backup de volta, por cima da VM de origem ou como uma nova VM. Todas as opções e o que acontece em cada caso estão em Backup e restauração.
Rede das VMs
network
osx-reims network [status]
osx-reims network bridge on [--port <porta>] [-y]
osx-reims network bridge off [-y]Sem argumento, mostra a ponte, as VMs que estão nela e as portas de rede com cabo. bridge on coloca uma porta com cabo deste computador (a da rota padrão, ou a de --port) na ponte osxbr0, que assume o endereço da porta; a ponte passa a subir com o computador. bridge off devolve à porta as configurações dela e é recusado com uma VM da ponte ligada. Os dois pedem a senha de administrador. Veja Rede.
| Opção | O que faz |
|---|---|
--port <nome> |
bridge on: a porta com cabo a usar, como enp6s0 |
-y, --yes |
Não pergunta |
Logs
logs
osx-reims logs [--json]Lista os logs das execuções recentes, do mais novo para o mais antigo: quando, qual ação, qual VM, como terminou e o arquivo — a mesma lista do View logs do console. Com --json, a lista sai como um único objeto JSON, para ser lida por um programa. Não grava nada.
Atualização do OSX-REIMS
update
osx-reims update [arquivo.deb] [opções]Instala uma versão nova do OSX-REIMS a partir do pacote .deb que você baixou do canal #osx-reims do Discord. O OSX-REIMS não baixa o pacote: o arquivo é o que você salvou. Sem um arquivo, ele procura osx-reims_*.deb na pasta Downloads, na Área de Trabalho, na sua pasta pessoal e na pasta atual, e pergunta qual usar quando há mais de um.
Ele lê o que o arquivo realmente é (com o dpkg-deb, não pelo nome), recusa outro pacote ou outra arquitetura, compara as versões e instala com o apt, para as dependências serem resolvidas. Uma atualização, a reinstalação da mesma versão e o retorno a uma versão anterior são confirmados cada um com as suas palavras. Todas as VMs precisam estar desligadas. Não é preciso ter rodado o setup nem ter aceito a licença: um ambiente quebrado é motivo para atualizar. Veja Atualizar e remover.
| Opção | O que faz |
|---|---|
--check |
Só diz qual versão está publicada; não instala nada |
-y, --yes |
Não pergunta, inclusive para reinstalar ou voltar a uma versão anterior |
A versão publicada e a impressão digital (SHA-256) do pacote dela são lidas de UPDATE_CHECK_URL, o único endereço que o OSX-REIMS consulta por conta própria. Como essa impressão digital chega ao computador por um caminho diferente do arquivo, um arquivo que combina com ela é o que foi publicado — o que o .sha256 salvo ao lado do arquivo não mostra, por ter vindo junto com ele. Um arquivo com a versão publicada, mas impressão digital diferente, não é instalado.
rebuild-reims
osx-reims rebuild-reims [opções]Compila o QEMU-Reims de novo, do zero, no commit do Reims vGPU que já está no computador: serve para uma compilação que funcionava e parou de funcionar, como depois de uma atualização do sistema. Nada é baixado nem atualizado — para trocar de versão, use o update-reims. Todas as VMs precisam estar desligadas.
A compilação atual não é apagada primeiro: ela é movida para o lado e removida só quando a nova passa nas verificações. Se a compilação ou as verificações falharem, ou se você interromper com Ctrl+C, a anterior volta ao lugar e as VMs iniciam como antes. Veja Versão do Reims vGPU.
| Opção | O que faz |
|---|---|
-y, --yes |
Não pergunta |
Início automático
autostart
osx-reims autostart [on|off|status] [VM] [opções]Define se uma VM abre sozinha quando o computador é ligado. Sem argumento, diz o que acontece hoje. Só uma VM pode ter o início automático, e ela precisa ter o macOS já instalado. A VM inicia com as próprias configurações salvas. Veja Configurações da VM.
| Argumento | O que faz |
|---|---|
on [VM] |
Aquela VM passa a iniciar logo depois do login na sessão; tira o início automático de qualquer outra |
off [VM] |
Aquela VM deixa de iniciar sozinha; uma VM em execução continua rodando |
status |
O que inicia com a sessão e se o computador faz login sozinho |
| Opção | O que faz |
|---|---|
--login |
Também liga o login automático do Ubuntu, sem pedir senha |
--no-login |
Volta a pedir a senha no login |
-y, --yes |
Não pergunta (--login e --no-login continuam valendo) |
A VM é iniciada por um serviço de usuário do systemd (osx-reims-vm@<VM>.service), que roda com a sessão gráfica: a janela da VM abre na tela da sessão, então ela não pode iniciar antes de alguém entrar. O login automático é uma configuração do próprio Ubuntu (/etc/gdm3/custom.conf) e nunca é mudada sem ser pedida; na primeira mudança, uma cópia do arquivo é guardada.
Instaladores
clean-cache
osx-reims clean-cache [versão|--all] [opções]Apaga os instaladores do macOS guardados em /opt/osx-reims/cache/: o Recovery de cada versão e downloads interrompidos. VMs já criadas não são afetadas, porque cada uma tem a própria cópia do instalador. A próxima criação com uma versão apagada baixa o instalador de novo. Sem versão nem --all, lista o cache e pergunta.
A versão é ventura, sonoma, sequoia ou tahoe.
| Opção | O que faz |
|---|---|
--all |
Apaga o cache inteiro, incluindo os componentes da EFI em cache/third-party/ |
-y, --yes |
Não pede confirmação |
Variáveis de ambiente
As variáveis REIMS_ROOT, RAILS_DIR, MACRECOVERY, QMP_TIMEOUT, NO_COLOR e UPDATE_CHECK_URL e o arquivo /etc/osx-reims.conf estão em Configuração avançada.