Vearch 3.5.9

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick Vearch 3.5.9 on Ubuntu 24.04 as the software version and your Region, then choose Launch through EC2.

Choose m5.large or larger, your key pair, and a security group as described in Prerequisites. Vearch keeps its vector indexes in memory, so size the instance's memory for your dataset. The AMI brings two EBS volumes: the root volume and a 30 GiB data volume for /var/lib/vearch. Enlarge the data volume at launch if you expect a large dataset.

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings 'DeviceName=/dev/sdf,Ebs={VolumeSize=100,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=vearch}]'

Connect over SSH with your key pair. For Vearch 3.5.9 on Ubuntu 24.04, the SSH user is ubuntu.

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot generates the certificate and the root password, starts Vearch, opens nginx and runs an authenticated check before it finishes. This takes well under a minute.

systemctl is-active vearch nginx vearch-firstboot vearch-port-guard
sudo test -f /var/lib/sac/data/vearch-firstboot.done && echo FIRSTBOOT_DONE

active active active active FIRSTBOOT_DONE

Vearch's own sockets belong to the vearch process. nginx (80, 443) and SSH (22) are the only services reachable from the network:

sudo ss -lntpH | grep -v '127.0.0.5' | awk '{split($6, p, "\""); print $4, p[2]}' | sort -u

*:8081 vearch *:8817 vearch *:8818 vearch *:9001 vearch 0.0.0.0:22 sshd 0.0.0.0:443 nginx 0.0.0.0:80 nginx 127.0.0.1:2370 vearch 127.0.0.1:2390 vearch 127.0.0.1:8898 vearch 127.0.0.1:8899 vearch [::]:22 sshd [::]:443 nginx [::]:80 nginx

In upstream Vearch, the router, master, partition server and monitor (9001, 8817, 8081, 8818) bind every interface, so this image filters them instead. The vearch service may exchange packets with loopback addresses only, and the sac_vearch firewall table drops those ports on every network interface. From another machine, they do not answer at all.

sudo grep -E '^VEARCH_' /root/vearch-credentials.txt

Only root can read the file:

VEARCH_URL=https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/ VEARCH_USER=root VEARCH_PASSWORD=<VEARCH_PASSWORD>

• VEARCH_URL is the API endpoint. It uses the instance's public DNS name from EC2 instance metadata (the public IP address when the subnet has no public DNS names). The certificate also names the public and private IP addresses. To serve Vearch under your own DNS name, see Step 10.
• VEARCH_USER and VEARCH_PASSWORD are the Vearch root user, which can do everything, including creating users and roles (Step 8).

Vearch uses HTTP Basic authentication. The examples below read the password from the credentials file and hand it to curl as a configuration file on standard input (-K -). This keeps the password out of command lines and your shell history.

Vearch reports a refused request in two ways. The document routes (/document/...) answer HTTP 401. The cluster routes that the router passes to the master (/dbs, /users, /roles, ...) answer with "code":3 in the JSON body. A successful call has "code":0.

C=/etc/ssl/vearch/vearch.crt; U=https://127.0.0.1 curl -s --cacert $C $U/dbs; echo printf 'user = "root:wrong-password"\n' | curl -s --cacert $C -K - $U/dbs; echo printf 'user = "root:secret"\n' | curl -s --cacert $C -K - $U/dbs; echo
sudo sed -n 's/^VEARCH_PASSWORD=\(.*\)/user = "root:\1"/p' /root/vearch-credentials.txt | curl -s --cacert $C -K - $U/dbs; echo curl -s --cacert $C -o /dev/null -w 'search without a password -> HTTP %{http_code}\n' -X POST -H 'Content-Type: application/json' --data '{"db_name":"x","space_name":"y","limit":1}' $U/document/search curl -s --cacert $C $U/healthz

{"code":3,"request_id":"ZTMxNTlhMW","msg":"auth header is empty"} {"code":3,"request_id":"MDI3ZjRiNT","msg":"auth header password is invalid"} {"code":3,"request_id":"MTMyOTJjZD","msg":"auth header password is invalid"} {"code":0,"request_id":"OGUyMTQwMj","data":[]} search without a password -> HTTP 401 ok

/healthz stays open for load balancers. It checks that the Vearch router answers and reveals nothing. From another machine, use VEARCH_URL instead of https://127.0.0.1, and use -k or the instance's certificate, because the certificate is self-signed.

A database holds spaces (Vearch's tables). A space declares scalar fields and one or more vector fields with their dimension and index. On this single node, create every space with "partition_num":1,"replica_num":1. Vearch 3.5's default of three replicas needs three partition servers.

Create the database movies and a space films with a title, a year and a 4-dimension vector indexed with FLAT (exact search, L2 distance). Then insert four films and search for the two nearest neighbours of a query vector:

C=/etc/ssl/vearch/vearch.crt; U=https://127.0.0.1 v() {
sudo sed -n 's/^VEARCH_PASSWORD=\(.*\)/user = "root:\1"/p' /root/vearch-credentials.txt | curl -s --cacert "$C" -K - -H 'Content-Type: application/json' "$@"; } v -X POST "$U/dbs/movies" | jq -c '{code, data}' v -X POST --data '{"name":"films","partition_num":1,"replica_num":1,"fields":[{"name":"title","type":"string"},{"name":"year","type":"integer"},{"name":"embedding","type":"vector","dimension":4,"index":{"name":"gamma","type":"FLAT","params":{"metric_type":"L2"}}}]}' "$U/dbs/movies/spaces" | jq -c '{code, name: .data.name, partitions: (.data.partitions | length)}' v -X POST --data '{"db_name":"movies","space_name":"films","documents":[{"_id":"1","title":"Carol","year":2015,"embedding":[0.9,0.1,0.1,0.0]},{"_id":"2","title":"Wonder Woman","year":2017,"embedding":[0.1,0.2,0.3,0.4]},{"_id":"3","title":"Life of Pi","year":2012,"embedding":[0.1,0.8,0.2,0.1]},{"_id":"4","title":"Mad Max: Fury Road","year":2015,"embedding":[0.2,0.3,0.3,0.4]}]}' "$U/document/upsert" | jq -c '{code, total: .data.total}' sleep 2 v -X POST --data '{"db_name":"movies","space_name":"films","vectors":[{"field":"embedding","feature":[0.1,0.2,0.3,0.35]}],"fields":["title","year"],"limit":2}' "$U/document/search" | jq -c '[.data.documents[0][] | {title, year, _score}]' v -X POST --data '{"db_name":"movies","space_name":"films","document_ids":["3"],"fields":["title"]}' "$U/document/query" | jq -c '.data.documents'

{"code":0,"data":{"id":1,"name":"movies"}} {"code":0,"name":"films","partitions":1} {"code":0,"total":4} [{"title":"Wonder Woman","year":2017,"_score":0.002500001108273864},{"title":"Mad Max: Fury Road","year":2015,"_score":0.02250000461935997}] [{"_id":"3","title":"Life of Pi"}]

_score is the L2 distance (smaller is closer). In a real application, you store the embeddings that your own model produces (any dimension). For large collections, pick an approximate index such as HNSW or IVFPQ. The Vearch documentation describes each index type and its parameters. Searches can also filter on scalar fields.

The image ships an end-to-end check that you can run at any time. First boot runs a read-only version of it.

The check reads the credentials file itself and talks to the API over HTTPS through nginx, with the instance's certificate pinned. It confirms that port 80 redirects and that an unknown host name is dropped. It confirms that a missing password, a wrong password and the upstream default password are refused, while the root password works on the same request. Finally, root creates a temporary database whose nearest-neighbour search returns the right document, and the check drops that database:

sudo vearch-verify.sh

port 80 -> 301 https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/ ; an unknown Host is dropped on 80 and 443 ; certificate verifies for ec2-<public-ip-dashed>.<region>.compute.amazonaws.com auth: /dbs code 3 with no / a wrong / the default password, code 0 with root; /document/search 401 without and with a wrong password, accepted for root round trip: root created sac_verify_<n>/vectors (FLAT L2), upserted 2 vectors, the nearest neighbour of [0.11,0.2,0.3,0.4] is 'near'; a wrong password cannot upsert (401); space and database dropped VEARCH_ROUNDTRIP_OK

Vearch has role-based access control. Create a role with the privileges an application needs and a user bound to it, so that applications do not use root. Privileges are per resource (ResourceDocument, ResourceSpace, ResourceDB, ...) with the level ReadOnly, WriteOnly, WriteRead or None. There are also built-in roles such as defaultDocumentAdmin. For example, create a search-only application user:

U=https://127.0.0.1; C=/etc/ssl/vearch/vearch.crt
sudo sed -n 's/^VEARCH_PASSWORD=\(.*\)/user = "root:\1"/p' /root/vearch-credentials.txt | curl -s --cacert $C -K - \
  -H 'Content-Type: application/json' -X POST --data '{"name":"app_reader","privileges":{"ResourceDocument":"ReadOnly"}}' $U/roles
sudo sed -n 's/^VEARCH_PASSWORD=\(.*\)/user = "root:\1"/p' /root/vearch-credentials.txt | curl -s --cacert $C -K - \
  -H 'Content-Type: application/json' -X POST --data '{"name":"app1","password":"<a-long-random-password>","role_name":"app_reader"}' $U/users

app1 can now search and query documents, but it cannot insert, update or delete them (HTTP 401). On this image, those levels are enforced. Upstream Vearch 3.5.2 to 3.5.9 ignored them (CVE-2026-108746), so a read-only role could write documents or grant itself privileges with PUT /roles. SecureAnyCloud's build applies the fix, and the image's build tests prove it with real users and roles.

Grant ResourceCache, ResourceUser and ResourceRole only to administrators, because the cache routes return stored user records.

The files that matter are locked down. The configuration file holds the root password as its sign key:

sudo stat -c '%a %U:%G %n' /etc/vearch/config.toml /root/vearch-credentials.txt /var/lib/vearch /etc/ssl/vearch/vearch.key

640 root:vearch /etc/vearch/config.toml 600 root:root /root/vearch-credentials.txt 750 vearch:vearch /var/lib/vearch 600 root:root /etc/ssl/vearch/vearch.key

The image records how the binaries were built, with the govulncheck result and the CVE patch:

sha256sum /opt/vearch/bin/vearch /opt/vearch/lib/libgamma_avx2.so grep -E '^(source|toolchain|binary|govulncheck) ' /usr/share/doc/sac/vearch/BUILD-PROVENANCE.txt

8d66498c348f781a92475cc85505efe94a4258808f389cfad36b006a34e88e95 /opt/vearch/bin/vearch 0e1b5142faab2651385962772c55982ed2b260ebcf3748e30169f4ae9d6aa548 /opt/vearch/lib/libgamma_avx2.so source https://github.com/vearch/vearch.git tag v3.5.9, commit 2de82d191fe3d775ab5b14855905de6c1d21cbfc (unmodified except go.mod/go.sum and the CVE-2026-108746 fix) toolchain go1.27.3 linux/amd64, official tarball https://go.dev/dl/go1.27.3.linux-amd64.tar.gz (sha256 65efbc80fdc1fa2cd2631cad5b481777a68e8725f34e89f50fc6ac714e379b40) binary /opt/vearch/bin/vearch sha256 8d66498c348f781a92475cc85505efe94a4258808f389cfad36b006a34e88e95 govulncheck v1.9.0 -mode=binary: only GO-2024-2430 GO-2024-2431 GO-2024-2432 GO-2024-2433 GO-2024-2434 (CubeFS CVE-2023-46738/46739/46740/46741/46742,

Vearch runs unprivileged in a sandbox that can write only to its data and log directories. It may exchange packets with loopback addresses only, so neither an S3 backup target nor anything else can reach the instance metadata service. nginx cannot reach the instance metadata service either:

systemctl show vearch -p User -p ProtectSystem -p ReadWritePaths -p NoNewPrivileges -p IPAddressDeny -p IPAddressAllow
systemctl show nginx -p IPAddressDeny

IPAddressAllow=::1/128 127.0.0.0/8 IPAddressDeny=::/0 0.0.0.0/0 User=vearch ReadWritePaths=/var/lib/vearch /var/log/vearch ProtectSystem=strict NoNewPrivileges=yes IPAddressDeny=fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32

Only the Vearch service account can open its cluster-management ports. Upstream, the master's node registration routes, the metadata store and the monitor's metrics and profiling pages need no password. The router port accepts only the Vearch account, nginx and root:

for p in 8817 8818 2370 9001; do curl -s -m 5 -o /dev/null -w "port $p as $(id -un) -> %{http_code}\n" http://127.0.0.1:$p/ || true; done
sudo nft list chain inet sac_vearch input | grep drop

port 8817 as ubuntu -> 000 port 8818 as ubuntu -> 000 port 2370 as ubuntu -> 000 port 9001 as ubuntu -> 000 iifname != "lo" tcp dport { 2370, 2378, 2390, 6060, 6061, 6062, 8081, 8817, 8818, 8898, 8899, 9001 } counter packets 0 bytes 0 drop

nginx passes Vearch a fixed host name and the real client address from the connection. It never passes values that a client sends:

grep -E 'proxy_set_header (Host|X-Forwarded-For|X-Real-IP|Forwarded)' /etc/nginx/vearch-proxy.conf

proxy_set_header Host $v_host; proxy_set_header Forwarded ""; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $remote_addr;

The certificate was generated on this instance and names its own addresses:

H=$(sudo sed -n 's#^VEARCH_URL=https://\([^/]*\)/.*#\1#p' /root/vearch-credentials.txt)
echo | openssl s_client -connect 127.0.0.1:443 -servername "$H" 2>/dev/null | openssl x509 -noout -subject -ext subjectAltName

subject=CN = ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, O = sac X509v3 Subject Alternative Name: DNS:ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, IP Address:<public-ip>, IP Address:<private-ip>, DNS:ip-<private-ip-dashed>.ec2.internal, IP Address:127.0.0.1, DNS:localhost

The password reached no log, the journal, shell history, backups or /etc (other than the configuration file). Check it with:

sudo vearch-secret-leak-check.sh

LEAKCHECK_OK the root password is in no journal, auth.log, syslog, cloud-init, nginx or Vearch log, shell history, MOTD, /var/backups, /etc (only config.toml), /usr/local, /opt or /tmp

Point a DNS record at the instance, then set the name that Vearch is served as. This command mints a new self-signed certificate for the name, updates nginx's host rule and the URL in /root/vearch-credentials.txt, reloads nginx and keeps the name across reboots:

sudo vearch-set-hostname <your-domain>

Without a configured name, the instance re-reads its address from EC2 instance metadata at every boot, so a stop and start that changes the public IP address keeps the API reachable.

To use a certificate from your own certificate authority instead, copy it over /etc/ssl/vearch/vearch.crt and vearch.key (key mode 0600) and run sudo systemctl reload nginx. Running vearch-set-hostname again replaces it with a self-signed one.

To generate a new root password, for example if the old one was ever exposed, run:

sudo vearch-rotate-root-password

This command changes the stored root user's password through the API (proving the old one) and writes the new sign key to /etc/vearch/config.toml. It then restarts Vearch, checks that the old password is refused and the new one works, and rewrites /root/vearch-credentials.txt. Update every client that used the old password.

Do not change root's password with PUT /users alone. Vearch's components use the sign key in the configuration file to talk to each other, so the two must stay the same.

Vearch's only outbound feature is backup and restore of a space to an S3-compatible endpoint named in the API request. This image blocks every outbound connection from the Vearch service, so a backup request cannot be pointed at the instance metadata service or anything else on your network. Searching and storing vectors need no outbound access.

To use S3 backups, allow outbound access by removing the drop-in and restarting Vearch. Point backups only at endpoints you trust, ideally an S3 VPC endpoint:

sudo rm /etc/systemd/system/vearch.service.d/60-sac-egress.conf
sudo systemctl daemon-reload && sudo systemctl restart vearch

Removing the drop-in also lets packets from other machines reach Vearch's sockets again. The sac_vearch firewall table still drops every Vearch port on the network interfaces, and the security group should still open only 22, 80 and 443.

Vearch stays blocked from the instance metadata service by the other drop-in, 50-sac-imds-deny.conf. Give backups an access key and secret in the request instead of relying on an instance role. To close outbound access again, recreate the file with IPAddressAllow=localhost and IPAddressDeny=any under [Service].

The data directory is its own EBS volume, mounted by filesystem UUID. Check the mount with:

findmnt -n -o SOURCE,FSTYPE,TARGET /var/lib/vearch; df -h /var/lib/vearch | tail -1

/dev/nvme1n1 ext4 /var/lib/vearch /dev/nvme1n1 30G 272M 28G 1% /var/lib/vearch

To grow it, enlarge the volume in the EC2 console (or with aws ec2 modify-volume). Then run sudo resize2fs /dev/nvme1n1 on the instance. No restart is needed. If the volume is ever missing, Vearch refuses to start instead of writing your data to the root disk.

EBS snapshots of the data volume are the simplest whole-dataset backup. For a consistent copy, stop Vearch (sudo systemctl stop vearch), snapshot the volume, and start Vearch again. The data volume contains the stored user records, so treat its snapshots as secret.

Settings live in /etc/vearch/config.base.toml, which holds no password. /etc/vearch/config.toml is rendered from the base file plus the sign key. Edit the base file, for example the log level, resource_limit_rate or the partition server's flush settings (see the Vearch configuration reference). Then re-render with the current password and restart:

sudo nano /etc/vearch/config.base.toml
sudo vearch-set-root-password --keep

Keep skip_auth = false, the master address = "127.0.0.1", every pprof_port = 0 and allow_origins = []. The service refuses to start otherwise. This image runs Vearch as a single node and is not set up to join other nodes.

/usr/bin/curl -s --cacert /etc/ssl/vearch/vearch.crt -K <(sudo sed -n 's/^VEARCH_PASSWORD=\(.*\)/user = "root:\1"/p' /root/vearch-credentials.txt) https://127.0.0.1/ | jq -c .data nginx -v 2>&1; lsb_release -ds ls /usr/share/doc/sac/vearch/

{"name":"vearch","version":{"build_time":"2026-02-04 17:51.22","build_version":"v3.5.9","commit_id":"2de82d191fe3d775ab5b14855905de6c1d21cbfc"}} nginx version: nginx/1.24.0 (Ubuntu) Ubuntu 24.04.5 LTS BUILD-PROVENANCE.txt CVE-2026-108746.patch LICENSE LICENSE.croaring LICENSE.faiss-MIT LICENSE.rocksdb-Apache-2.0 LICENSE.rocksdb-GPL-2.0 LICENSE.rocksdb-leveldb-BSD THIRD-PARTY-NOTICES.txt govulncheck-binary.json govulncheck-binary.txt

• Vearch 3.5.9: /opt/vearch/bin/vearch, service vearch (master, router and partition server), data in /var/lib/vearch (own EBS volume), logs in /var/log/vearch.
• gamma engine 3.5.9: /opt/vearch/lib/libgamma_avx2.so with faiss 1.10.0, RocksDB 9.2.1 and CRoaring 4.2.1, plus Ubuntu's protobuf, oneTBB and OpenBLAS.
• nginx 1.24.0: TLS on 443, redirect on 80, site /etc/nginx/sites-available/sac-vearch.
• Ubuntu 24.04 LTS: unattended security upgrades on.

The engine is built for CPUs with AVX2, which every current EC2 x86 instance type has.