Page about emulated devices
This commit is contained in:
parent
a81775117c
commit
827fe8b637
|
@ -6,6 +6,7 @@
|
||||||
|
|
||||||
- [Architecture](./architecture.md)
|
- [Architecture](./architecture.md)
|
||||||
- [Source code, Building, and Installation](./install.md)
|
- [Source code, Building, and Installation](./install.md)
|
||||||
|
- [Running on an emulated device](./emulator.md)
|
||||||
- [Glossary](./glossary.md)
|
- [Glossary](./glossary.md)
|
||||||
|
|
||||||
# User and Administration Guide
|
# User and Administration Guide
|
||||||
|
|
|
@ -0,0 +1,84 @@
|
||||||
|
# How to get Synit running on an emulated PostmarketOS device
|
||||||
|
|
||||||
|
[vouch.id]: https://vouch.id/
|
||||||
|
|
||||||
|
Begin by following the [generic PostmarketOS instructions for running using
|
||||||
|
QEMU](https://wiki.postmarketos.org/wiki/QEMU_amd64_(qemu-amd64)), reprised here briefly, and
|
||||||
|
then build and install the Synit packages and (optionally) the SqueakPhone user interface.
|
||||||
|
|
||||||
|
## Build and install `qemu-amd64` PostmarketOS
|
||||||
|
|
||||||
|
First, run `pmbootstrap init` (choose `qemu`, `amd64`, and a `console` UI); or, if you've done
|
||||||
|
that previously, run `pmbootstrap config device qemu-amd64`.
|
||||||
|
|
||||||
|
Then, run `pmbootstrap qemu --video 720x1440@60` to create an emulated PostmarketOS device and
|
||||||
|
start it. You'll run that same command each time you boot up the machine, so create an alias or
|
||||||
|
script for it, if you like.
|
||||||
|
|
||||||
|
## Set up `ssh` access to the emulated device
|
||||||
|
|
||||||
|
I have the following stanza in my `~/.ssh/config`:
|
||||||
|
|
||||||
|
```
|
||||||
|
Host pm-qemu
|
||||||
|
HostName localhost
|
||||||
|
Port 2222
|
||||||
|
User user
|
||||||
|
StrictHostKeyChecking no
|
||||||
|
UserKnownHostsFile /dev/null
|
||||||
|
```
|
||||||
|
|
||||||
|
Log in to the device using a username and password (`SSH_AUTH_SOCK= ssh pm-qemu`) and set up
|
||||||
|
SSH key access via `~/.ssh/authorized_keys` on the device, however you like to do it. I use
|
||||||
|
[vouch.id][] to log into my machines using an SSH certificate, so I do the
|
||||||
|
following:
|
||||||
|
|
||||||
|
```
|
||||||
|
mkdir -p .local/bin
|
||||||
|
cd .local/bin
|
||||||
|
wget https://vouch.id/download/vouch
|
||||||
|
chmod a+x
|
||||||
|
sudo apk add python3
|
||||||
|
echo 'export VOUCH_ID_PRINCIPAL=tonyg@leastfixedpoint.com' >> ~/.profile
|
||||||
|
```
|
||||||
|
|
||||||
|
Then I log out and back in again to pick up the `VOUCH_ID_PRINCIPAL` variable, followed by
|
||||||
|
running
|
||||||
|
|
||||||
|
```
|
||||||
|
vouch server setup --accept-principals tonyg
|
||||||
|
```
|
||||||
|
|
||||||
|
(Substitute your own preferred certificate principal username, of course.) After this, I can
|
||||||
|
use the [vouch.id][] app to authorize SSH logins.
|
||||||
|
|
||||||
|
## Allow port forwarding over SSH to the device
|
||||||
|
|
||||||
|
Edit `/etc/ssh/sshd_config` to have `AllowTcpForwarding yes`. This will let you use e.g.
|
||||||
|
port-forwarded VNC over your SSH connection to the device once you have the user interface set
|
||||||
|
up.
|
||||||
|
|
||||||
|
## Build and install the packages
|
||||||
|
|
||||||
|
Follow the [build and installation instructions](./install.md) to check out and build the code.
|
||||||
|
|
||||||
|
Once you've checked out the `synit` module and have all the necessary build dependencies
|
||||||
|
installed, change directory to `synit/packaging/squid` and run `start.sh` in one terminal
|
||||||
|
window. Leave this open for the remainder of the build process. Open another terminal, go to
|
||||||
|
`synit/packaging`, and run `make keyfile`. Then, run `make ARCH=x86_64`.
|
||||||
|
|
||||||
|
Hopefully the build will complete successfully. Once it has done so, change to `synit/scripts`
|
||||||
|
and run `./upload-bundle.sh pm-qemu`. Then log in to the emulated device and run the
|
||||||
|
`./transmogrify.sh` script from the `/home/user` directory. Reboot the device. When it comes
|
||||||
|
back, you will find that it is running Synit (check `ps` output to see that `synit-pid1` is in
|
||||||
|
fact PID 1).
|
||||||
|
|
||||||
|
## Build and install the user interface packages
|
||||||
|
|
||||||
|
If you want to run the SqueakPhone image on your local machine, ensure your Unix user is in the
|
||||||
|
`input` group.
|
||||||
|
|
||||||
|
squeak-phone: ./push-image-to-phone.sh pm-qemu
|
||||||
|
|
||||||
|
set `dpi.override` to have 256 in it
|
||||||
|
|
|
@ -24,24 +24,28 @@ Synit builds upon many existing technologies, but primarily relies on the follow
|
||||||
|
|
||||||
- Rust nightly and Cargo (perhaps installed via [rustup](https://rustup.rs/)).
|
- Rust nightly and Cargo (perhaps installed via [rustup](https://rustup.rs/)).
|
||||||
|
|
||||||
|
- The rust `cross` tool (even for `x86_64` builds):
|
||||||
|
|
||||||
|
```
|
||||||
|
cargo install cross
|
||||||
|
```
|
||||||
|
|
||||||
|
- Docker (containers are used frequently for building packages, among other things!)
|
||||||
|
|
||||||
- Python 3.9 or greater
|
- Python 3.9 or greater
|
||||||
|
|
||||||
- `git`, `ssh`, `rsync`
|
- `git`, `ssh`, `rsync`
|
||||||
|
|
||||||
- Make, a C compiler, and so on; standard Unix programming tools.
|
- Make, a C compiler, and so on; standard Unix programming tools.
|
||||||
|
|
||||||
- Docker (containers are used frequently for (cross-)building of Alpine packages, among other
|
|
||||||
things!)
|
|
||||||
|
|
||||||
- The `preserves-tool` binary installed on your `PATH`:
|
- The `preserves-tool` binary installed on your `PATH`:
|
||||||
|
|
||||||
```
|
```
|
||||||
cargo install preserves-tools
|
cargo install preserves-tools
|
||||||
```
|
```
|
||||||
|
|
||||||
- <a id="binfmt"></a>For cross builds (e.g. the very common case of building for `aarch64` on
|
- <a id="binfmt"></a>`qemu` and its `binfmt` support (even for `x86_64` builds). On Debian,
|
||||||
an `x86_64` host), `qemu` and its `binfmt` support. On Debian, `apt install binfmt-support
|
`apt install binfmt-support qemu-user-static`.[^debian-qemu-bug]
|
||||||
qemu-user-static`.[^debian-qemu-bug]
|
|
||||||
|
|
||||||
- Source code for Synit components (see below).
|
- Source code for Synit components (see below).
|
||||||
|
|
||||||
|
@ -52,7 +56,8 @@ Synit builds upon many existing technologies, but primarily relies on the follow
|
||||||
- **Great tolerance for the possibility of soft-bricking your phone.** This is experimental
|
- **Great tolerance for the possibility of soft-bricking your phone.** This is experimental
|
||||||
software! When it breaks, you'll often have to (at least) reinstall PostmarketOS from
|
software! When it breaks, you'll often have to (at least) reinstall PostmarketOS from
|
||||||
absolute scratch on the machine. I do lots of development using `qemu-amd64` for this
|
absolute scratch on the machine. I do lots of development using `qemu-amd64` for this
|
||||||
reason.
|
reason. See [here](./emulator.md) for [instructions on running Synit on a emulated
|
||||||
|
device](./emulator.md).
|
||||||
|
|
||||||
## Get the code
|
## Get the code
|
||||||
|
|
||||||
|
|
|
@ -19,10 +19,9 @@ Linux's Unix heritage.
|
||||||
|
|
||||||
## Quickstart
|
## Quickstart
|
||||||
|
|
||||||
If you have a mobile phone or computer capable of running
|
You can [run Synit on an emulated device](./emulator.md), or if you have a mobile phone or
|
||||||
[PostmarketOS](https://postmarketos.org/), then you can
|
computer capable of running [PostmarketOS](https://postmarketos.org/), then you can
|
||||||
[install](./install.md) the software to try it out. You can also run
|
[install](./install.md) the software on your device to try it out.
|
||||||
Synit inside a virtual machine.
|
|
||||||
|
|
||||||
See the [installation instructions](./install.md) for a list of
|
See the [installation instructions](./install.md) for a list of
|
||||||
supported devices.
|
supported devices.
|
||||||
|
|
Loading…
Reference in New Issue