mirror of
https://github.com/xxh/xxh
synced 2024-11-14 08:17:18 +00:00
docs: add vagrant documentation/scripts
This commit is contained in:
parent
6873f1b5be
commit
9db40056dd
5 changed files with 104 additions and 25 deletions
57
README.md
57
README.md
|
@ -1,6 +1,6 @@
|
|||
<p align="center">You stuffed command shell with aliases, tools and colors but you lose it all when using ssh. The mission of xxh is to bring your favorite shell wherever you go through ssh without root access and system installations.</p>
|
||||
|
||||
<p align="center">
|
||||
<p align="center">
|
||||
If you like the idea of xxh click ⭐ on the repo and <a href="https://twitter.com/intent/tweet?text=Bring%20your%20favorite%20shell%20wherever%20you%20go%20through%20the%20ssh.&url=https://github.com/xxh/xxh" target="_blank">tweet</a>.
|
||||
</p>
|
||||
|
||||
|
@ -19,13 +19,13 @@ If you like the idea of xxh click ⭐ on the repo and <a href="https://twitter.c
|
|||
<tr style="border: 0px !important;">
|
||||
<td valign="top" style="border: 0px !important;"><b>Be open and fork-ready</b>. Every xxh repo could be forked, customized and reused without waiting for a package management system, xxh release or any third party packages. Five shells are currently supported and more could be added by the community.</td>
|
||||
<td valign="top" style="border: 0px !important;"><b>Do more</b>. The xxh packages are not only about shells. Any type of tool or code could be behind an entrypoint. If you want to run <a href="https://github.com/browsh-org/browsh">browsh</a> on the remote host, just put its portable version as an entrypoint in the xxh-shell.</td>
|
||||
<td valign="top" style="border: 0px !important;"><b>Chameleon</b>. Switching the shells is as easy as possible and you don't have to be locked in to one shell. Choose your current shell based on the task you want to solve: <code>xxh anyhost +s xonsh</code> for a python environment, osquery for simple querying, fish for modern features or time-tested zsh and bash for speed. </td>
|
||||
<td valign="top" style="border: 0px !important;"><b>Chameleon</b>. Switching the shells is as easy as possible and you don't have to be locked in to one shell. Choose your current shell based on the task you want to solve: <code>xxh anyhost +s xonsh</code> for a python environment, osquery for simple querying, fish for modern features or time-tested zsh and bash for speed. </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## Installation methods
|
||||
#### [PyPi 3](https://pypi.org/project/xxh-xxh/)
|
||||
#### [PyPi 3](https://pypi.org/project/xxh-xxh/)
|
||||
```shell script
|
||||
pip3 install xxh-xxh
|
||||
```
|
||||
|
@ -73,7 +73,7 @@ Currently supported OS for target host is Linux on x86_64.
|
|||
|
||||
| xxh-shell | status | [xxh-plugins](https://github.com/xxh/xxh/wiki#plugins) | [seamless](https://github.com/xxh/xxh/wiki#seamless-mode) | demo |
|
||||
|-----------------------------------------------------------------------|------------|-------------|---------|------|
|
||||
| **[xonsh](https://github.com/xxh/xxh-shell-xonsh)** | stable | [autojump](https://github.com/xxh/xxh-plugin-xonsh-autojump), [[+]](https://github.com/xxh/xxh-plugin-xonsh-example) | `xxh.xsh` | <a href="https://asciinema.org/a/osSEzqnmH9pMYEZibNe2K7ZL7" target="_blank">demo</a> |
|
||||
| **[xonsh](https://github.com/xxh/xxh-shell-xonsh)** | stable | [autojump](https://github.com/xxh/xxh-plugin-xonsh-autojump), [[+]](https://github.com/xxh/xxh-plugin-xonsh-example) | `xxh.xsh` | <a href="https://asciinema.org/a/osSEzqnmH9pMYEZibNe2K7ZL7" target="_blank">demo</a> |
|
||||
| **[zsh](https://github.com/xxh/xxh-shell-zsh)** | stable | [ohmyzsh](https://github.com/xxh/xxh-plugin-zsh-ohmyzsh), [p10k](https://github.com/xxh/xxh-plugin-zsh-powerlevel10k), [[+]](https://github.com/xxh/xxh-plugin-zsh-example) | `xxh.zsh` | <a href="https://asciinema.org/a/rCiT9hXQ5IdwqOwg6rifyFZzb" target="_blank">demo</a> |
|
||||
| **[fish](https://github.com/xxh/xxh-shell-fish)** | stable | [ohmyfish](https://github.com/xxh/xxh-plugin-fish-ohmyfish), [fisher](https://github.com/xxh/xxh-plugin-fish-fisher), [userconfig](https://github.com/xxh/xxh-plugin-fish-userconfig), [[+]](https://github.com/xxh/xxh-plugin-fish-example) | [todo](https://github.com/xxh/xxh/issues/74) |
|
||||
| **[bash](https://github.com/xxh/xxh-shell-bash)** | stable | [ohmybash](https://github.com/xxh/xxh-plugin-bash-ohmybash), [[+]](https://github.com/xxh/xxh-plugin-bash-example) | `xxh.bash` | <a href="https://asciinema.org/a/314508" target="_blank">demo</a> |
|
||||
|
@ -81,10 +81,10 @@ Currently supported OS for target host is Linux on x86_64.
|
|||
| **[fish-appimage](https://github.com/xxh/xxh-shell-fish-appimage)** | alpha | | | |
|
||||
| **[elvish](https://github.com/krageon/xxh-shell-elvish)** | alpha | | | |
|
||||
|
||||
[Search xxh shell on Github](https://github.com/search?q=xxh-shell&type=Repositories) or [Bitbucket](https://bitbucket.org/repo/all?name=xxh-shell) or [create your shell entrypoint](https://github.com/xxh/xxh-shell-example) to use another portable shell.
|
||||
[Search xxh shell on Github](https://github.com/search?q=xxh-shell&type=Repositories) or [Bitbucket](https://bitbucket.org/repo/all?name=xxh-shell) or [create your shell entrypoint](https://github.com/xxh/xxh-shell-example) to use another portable shell.
|
||||
|
||||
### Prerun plugins
|
||||
[Prerun plugins](https://github.com/xxh/xxh/wiki#plugins) allow you to bring any portable tools, dotfiles or aliases to xxh session before running shell.
|
||||
[Prerun plugins](https://github.com/xxh/xxh/wiki#plugins) allow you to bring any portable tools, dotfiles or aliases to xxh session before running shell.
|
||||
|
||||
Pinned plugins: **[core](https://github.com/xxh/xxh-plugin-prerun-core)** (xxh-sudo, xxh-screen, xxh-tmux), **[dotfiles](https://github.com/xxh/xxh-plugin-prerun-dotfiles)**, **[docker](https://github.com/xxh/xxh-plugin-prerun-docker)**, **[python](https://github.com/xxh/xxh-plugin-prerun-python)**, **[xxh](https://github.com/xxh/xxh-plugin-prerun-xxh)**, **[vim](https://github.com/xxh/xxh-plugin-prerun-vim)**, **[zoxide](https://github.com/xxh/xxh-plugin-prerun-zoxide)**, **[starship](https://github.com/izissise/xxh-plugin-prerun-starship)**. There is [cookiecutter template to create prerun plugin](https://github.com/xxh/cookiecutter-xxh-plugin-prerun).
|
||||
|
||||
|
@ -111,7 +111,7 @@ xxh local +s xonsh # Experimental: build xxh envi
|
|||
For reusing arguments and simplifying xxh usage (like shortening to `xxh anyhost`) there is a [config file](https://github.com/xxh/xxh/wiki#config-file).
|
||||
|
||||
**Why the plus sign for the xxh arguments?** The xxh is using the plus sign for the xxh arguments to save the ability to use the minus sign for the original ssh arguments. This allows just replace the first two letters in the `ssh` command to convert it to the `xxh` command. Also see the [discussion](https://github.com/xxh/xxh/issues/129).
|
||||
|
||||
|
||||
### Installing xxh packages
|
||||
```bash
|
||||
xxh [+I xxh-package +I ...] [+L] [+RI xxh-package +RI ...] [+R xxh-package +R ...]
|
||||
|
@ -131,11 +131,11 @@ xxh +I xxh-shell-example+path+/home/user/my-xxh-dev/xxh-shell-example
|
|||
|
||||
This is experimental magic. Please read the text below twice.
|
||||
|
||||
If you have shell access on the host or you're in a docker container and you can't ssh to it
|
||||
then you can download and build hermetic xxh environment inplace. The `xxh local` command works
|
||||
If you have shell access on the host or you're in a docker container and you can't ssh to it
|
||||
then you can download and build hermetic xxh environment inplace. The `xxh local` command works
|
||||
exactly like `xxh remote_host` and creates a hermetic environment in `~/.xxh` by default.
|
||||
|
||||
At this time we don't have portable build tools like `git`, `wget`, `curl`, `tar` and others which
|
||||
At this time we don't have portable build tools like `git`, `wget`, `curl`, `tar` and others which
|
||||
could be required by some xxh package build scripts. When running `xxh local` it is expected that the tools are present on the host.
|
||||
|
||||
To run xxh inplace on Linux x86_64 just copy and paste these bash commands:
|
||||
|
@ -146,7 +146,7 @@ XH=~/.xxh \
|
|||
&& ( [[ -x $(command -v curl) ]] && curl -L $XD || wget -O- $XD ) | tar zxf - xxh \
|
||||
&& echo 'Usage: ./xxh local [+s xonsh/zsh/fish/osquery/bash]'
|
||||
```
|
||||
Next time you're on host just run `~/.xxh/xxh local` and you will enter your xxh environment.
|
||||
Next time you're on host just run `~/.xxh/xxh local` and you will enter your xxh environment.
|
||||
|
||||
## Examples of use cases
|
||||
### Python with pip everywhere without installation
|
||||
|
@ -157,7 +157,7 @@ xxh anyhost +s xonsh
|
|||
anyhost> python --version
|
||||
Python 3.8.2
|
||||
```
|
||||
You'll get python-powered [xonsh](https://xon.sh) shell with portable python and pip on the host without any system installations on the host.
|
||||
You'll get python-powered [xonsh](https://xon.sh) shell with portable python and pip on the host without any system installations on the host.
|
||||
You can install PyPi packages manually or bring them with you automatically by using [xxh-plugin-prerun-dotfiles](https://github.com/xxh/xxh-plugin-prerun-dotfiles). Also don't forget about xxh-plugins like [zoxide](https://github.com/xxh/xxh-plugin-prerun-zoxide).
|
||||
|
||||
#### Way 2. Using portable python on any xxh shell
|
||||
|
@ -169,7 +169,7 @@ anyhost> python --version
|
|||
Python 3.8.2
|
||||
anyhost> pip install pandas
|
||||
```
|
||||
Using [xxh-plugin-prerun-python](https://github.com/xxh/xxh-plugin-prerun-python) you'll get a portable
|
||||
Using [xxh-plugin-prerun-python](https://github.com/xxh/xxh-plugin-prerun-python) you'll get a portable
|
||||
Python AppImage which can be used on a host without python and with any xxh shell.
|
||||
|
||||
### Using docker on host without root access
|
||||
|
@ -180,7 +180,7 @@ xxh +RI xxh-plugin-prerun-docker
|
|||
xxh anyhost +if
|
||||
|
||||
anyhost> xxh-docker-run
|
||||
anyhost> docker ps
|
||||
anyhost> docker ps
|
||||
CONTAINER ID IMAGE COMMAND
|
||||
anyhost> docker run --rm hello-world | grep Hello
|
||||
Hello from Docker!
|
||||
|
@ -189,14 +189,14 @@ anyhost> xxh-docker-stop
|
|||
|
||||
### Bring dotfiles to xxh session
|
||||
|
||||
There is the [xxh-plugin-prerun-dotfiles](https://github.com/xxh/xxh-plugin-prerun-dotfiles) plugin which creates config files
|
||||
There is the [xxh-plugin-prerun-dotfiles](https://github.com/xxh/xxh-plugin-prerun-dotfiles) plugin which creates config files
|
||||
when you go to the host using xxh. You can fork it and create your cozy settings once and forever.
|
||||
|
||||
### Seamless Oh My Zsh ([demo](https://asciinema.org/a/rCiT9hXQ5IdwqOwg6rifyFZzb))
|
||||
```shell script
|
||||
source xxh.zsh anyhost +I xxh-plugin-zsh-ohmyzsh +if +q
|
||||
source xxh.zsh anyhost +I xxh-plugin-zsh-ohmyzsh +if +q
|
||||
```
|
||||
This command brings your current Oh My Zsh session theme to the xxh session. If you need more complex settings just fork
|
||||
This command brings your current Oh My Zsh session theme to the xxh session. If you need more complex settings just fork
|
||||
the [xxh-plugin-zsh-ohmyzsh](https://github.com/xxh/xxh-plugin-zsh-ohmyzsh) and hack it.
|
||||
|
||||
### Read host as a table with [osquery](https://github.com/xxh/xxh-shell-osquery)
|
||||
|
@ -208,11 +208,11 @@ osquery> SELECT * FROM users WHERE username='news';
|
|||
+-----+-----+----------+-------------+-----------------+-------------------+
|
||||
| 9 | 9 | news | news | /var/spool/news | /usr/sbin/nologin |
|
||||
+-----+-----+----------+-------------+-----------------+-------------------+
|
||||
```
|
||||
```
|
||||
|
||||
### All in one portable home
|
||||
xxh is very agile. You can create your own `xxh-shell` (the shell part means it has an entrypoint) which can have any portable tools
|
||||
that could help you on the host. [Bash](https://github.com/xxh/xxh-shell-bash) xxh-shell is one of these
|
||||
that could help you on the host. [Bash](https://github.com/xxh/xxh-shell-bash) xxh-shell is one of these
|
||||
platforms that could be forked and stuffed.
|
||||
|
||||
## [Questions and answers](https://github.com/xxh/xxh/wiki)
|
||||
|
@ -240,17 +240,24 @@ platforms that could be forked and stuffed.
|
|||
- [New questions](https://github.com/xxh/xxh/wiki#new-questions)
|
||||
|
||||
## Development
|
||||
In the [xxh development environment](https://github.com/xxh/xxh/tree/master/xde) there is full [dockerised](https://www.docker.com/) environment
|
||||
for development, testing and contribution. The process of testing and development is orchestrated by `xde` tool and is as
|
||||
|
||||
### xxh Development Environment
|
||||
|
||||
In the [xxh development environment](https://github.com/xxh/xxh/tree/master/xde) there is full [dockerised](https://www.docker.com/) environment
|
||||
for development, testing and contribution. The process of testing and development is orchestrated by `xde` tool and is as
|
||||
easy as possible.
|
||||
|
||||
**We have teams.** If you're in a team it does not mean you have an obligation to do something. The main goal of teams is to create groups
|
||||
### Vagrant based Plugin Development
|
||||
|
||||
To develop plugins, [Vagrant](https://www.vagrantup.com) supports starting [many configurations](https://app.vagrantup.com/boxes/search) of
|
||||
|
||||
**We have teams.** If you're in a team it does not mean you have an obligation to do something. The main goal of teams is to create groups
|
||||
of passionate people who could help or support solving complex problems. Some people could be an expert in one shell and a
|
||||
newbie in another shell and mutual assistance is the key to xxh evolution. [Ask join.](https://github.com/xxh/xxh/issues/50)
|
||||
|
||||
## Thanks
|
||||
* **niess** for great [python-appimage](https://github.com/niess/python-appimage)
|
||||
* **niess** for great [python-appimage](https://github.com/niess/python-appimage)
|
||||
* **probonopd** and **TheAssassin** for hard-working [AppImage](https://github.com/AppImage)
|
||||
* **Anthony Scopatz**, **Gil Forsyth**, **Jamie Bliss**, **David Strobach**, **Morten Enemark Lund** and **@xore** for amazing [xonsh shell](https://github.com/xonsh/xonsh)
|
||||
* **Roman Perepelitsa** for incredible [statically-linked, hermetic, relocatable Zsh](https://github.com/romkatv/zsh-bin)
|
||||
* **Roman Perepelitsa** for incredible [statically-linked, hermetic, relocatable Zsh](https://github.com/romkatv/zsh-bin)
|
||||
* **Johannes Altmanninger** and **Fabian Homborg** for extensive and portable [fish shell](https://github.com/fish-shell/fish-shell)
|
||||
|
|
44
plugin-development/README.md
Normal file
44
plugin-development/README.md
Normal file
|
@ -0,0 +1,44 @@
|
|||
# Plugin Development using Vagrant
|
||||
|
||||
[Vagrant](https://www.vagrantup.com) from HashiCorp creates virtual environments that can easily allow unique testing destinations for your plugin development.
|
||||
|
||||
To develop using `Vagrant`, copy this folder to a new location and change the `config.vm.box` to the [a supported VN](https://app.vagrantup.com/boxes/search) that you would like to target.
|
||||
|
||||
## Functionality
|
||||
|
||||
You can start the VM using the following `Vagrantfile`:
|
||||
|
||||
```Vagrantfile
|
||||
# vi: set ft=ruby :
|
||||
Vagrant.configure("2") do |config|
|
||||
config.vm.box = "ubuntu/jammy64"
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
Start the environment using:
|
||||
|
||||
```sh
|
||||
vagrant up
|
||||
```
|
||||
|
||||
A typical development folder might look like this:
|
||||
|
||||
```
|
||||
-rwxrwxr-x 1 mcrowe mcrowe 940 Feb 13 11:32 start.sh*
|
||||
-rw-rw-r-- 1 mcrowe mcrowe 3020 Feb 13 08:05 Vagrantfile
|
||||
drwxrwxr-x 4 mcrowe mcrowe 4096 Feb 13 10:08 xxh-plugin-bash-bashit/
|
||||
drwxrwxr-x 4 mcrowe mcrowe 4096 Feb 13 08:56 xxh-plugin-prerun-dotbare/
|
||||
```
|
||||
|
||||
The `start.sh` script starts an `xxh` session to the VM and maps in any `xxh-` folders in the session. For example:
|
||||
|
||||
To reset everything and start again:
|
||||
|
||||
```sh
|
||||
vagrant destroy && vagrant up
|
||||
```
|
||||
|
||||
## Demo
|
||||
|
||||
![demo](demo.gif)
|
4
plugin-development/Vagrantfile
vendored
Normal file
4
plugin-development/Vagrantfile
vendored
Normal file
|
@ -0,0 +1,4 @@
|
|||
# vi: set ft=ruby :
|
||||
Vagrant.configure("2") do |config|
|
||||
config.vm.box = "ubuntu/jammy64"
|
||||
end
|
BIN
plugin-development/demo.gif
Normal file
BIN
plugin-development/demo.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 1.7 MiB |
24
plugin-development/start.sh
Executable file
24
plugin-development/start.sh
Executable file
|
@ -0,0 +1,24 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
SHELL=${1:-bash}
|
||||
|
||||
VAGRANT_IP="$(VBoxManage showvminfo $(cat .vagrant/machines/default/virtualbox/id) --details | grep 'name = ssh' | cut -b 18- | egrep -o 'host ip = [0-9.]*' | cut -b 11-)"
|
||||
VAGRANT_PORT="$(VBoxManage showvminfo $(cat .vagrant/machines/default/virtualbox/id) --details | grep 'name = ssh' | cut -b 18- | egrep -o 'host port = [0-9]*' | cut -b 13-
|
||||
)"
|
||||
SSH="-i .vagrant/machines/default/virtualbox/private_key -o PasswordAuthentication=no vagrant@$VAGRANT_IP -p $VAGRANT_PORT"
|
||||
|
||||
TESTING=""
|
||||
CURR_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
||||
|
||||
for item in $(shopt -s dotglob && cd $CURR_DIR && find . -type d -name 'xxh-*'); do
|
||||
TODO="$(basename $item)"
|
||||
TESTING="+RI $TODO+path+$CURR_DIR/$TODO $TESTING"
|
||||
done
|
||||
|
||||
echo "Starting with params: $TESTING"
|
||||
ssh $SSH "ls -l"
|
||||
if [ $? != 0 ]; then
|
||||
ssh-keygen -f "$HOME/.ssh/known_hosts" -R "[$VAGRANT_IP]:$VAGRANT_PORT"
|
||||
fi
|
||||
|
||||
xxh $SSH +s $SHELL $TESTING
|
Loading…
Reference in a new issue