V3
Databases AWS

Vearch 3.5.9 on AWS User Guide

| Product: Vearch 3.5.9 on Ubuntu 24.04 on AWS

Overview

This guide covers launching and using the Vearch 3.5.9 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg vector databases and RAG listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

Vearch is an open source vector database for similarity search over embeddings, originally built for visual search at JD.com. It stores high dimensional vectors next to ordinary scalar fields and returns the nearest neighbours of a query vector in milliseconds, with FLAT, IVF, HNSW and other index types on the faiss based gamma engine. It is used as the retrieval layer for retrieval augmented generation (RAG), semantic and image search, recommendation and near duplicate detection. Applications talk to it over a JSON REST API.

Vearch is distributed by design: a master keeps the schema and cluster metadata, a router serves the API and merges results, and a partition server stores and indexes the documents. This image runs upstream's documented single node mode, in which all three roles run in one process with an embedded metadata store, so the whole database is this one instance and it answers queries as soon as first boot finishes.

The cloudimg image ships it the secure way:

  • A root password unique to your instance. Vearch's root password is its cluster sign key. The image ships no configuration, no data and no root user; first boot generates a 48 character password on the instance, starts Vearch so that the root user is created with it, and writes it to /root/vearch-credentials.txt (root only). The upstream default password is never accepted.
  • HTTPS from the first boot. nginx serves the API on port 443 with a certificate generated on your instance's first boot. Port 80 redirects to HTTPS. Vearch authenticates every request with HTTP Basic authentication, so credentials only ever cross the network inside TLS.
  • Every Vearch port on localhost only. Upstream Vearch binds its router, master and partition server ports on every interface and serves some internal routes (node registration, metrics and profiling) without authentication. On this image a kernel filter on the Vearch service lets its sockets talk to loopback addresses only, a firewall table drops every Vearch port on the network interfaces, and on the instance itself only the Vearch service account can open the internal ports. nginx is the only network listener.
  • Built from source, patched. The official Vearch 3.5.9 binary was built with an older Go toolchain and libraries that have published security fixes. cloudimg builds Vearch from the v3.5.9 source with Go 1.27.3 and patched Go modules, links the vector engine against Ubuntu's own (security updated) protobuf, oneTBB and OpenBLAS libraries, and applies cloudimg's backport of the published fix for CVE-2026-108746 (custom roles ignored their read only or write only privilege level). This is Vearch 3.5.9 with that cloudimg backport, not an upstream release: upstream has not yet released a fix. The change is the one function in internal/entity/user.go; the exact diff ships at /usr/share/doc/cloudimg/vearch/CVE-2026-108746.patch with a notice that cloudimg modified that file.
  • Closed until first boot, and fail closed. Vearch cannot start before first boot has written its password, and nginx ships switched off. First boot opens the public listener only after Vearch works on loopback and an authenticated check passes; if anything fails, the listener is closed again. The service also refuses to start if its configuration ever loses the password, turns authentication off, enables profiling or cross origin access, or finds its data volume missing.
  • Your data on its own disk. /var/lib/vearch (metadata store, raft logs and vector data) is a separate 30 GiB EBS volume that you can resize independently of the operating system.
  • Hardened defaults. Vearch runs as its own unprivileged account in a systemd sandbox that can write only to its data and log directories. It can make no outbound connection and cannot reach the instance metadata service (see Step 11 for S3 backups). nginx is blocked from the instance metadata service too. The AMI requires IMDSv2. Requests for any host name the instance does not serve are dropped.
  • Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: Vearch 3.5.9 (/opt/vearch/bin/vearch and the gamma engine /opt/vearch/lib/libgamma_avx2.so, built from source by cloudimg when the image was made), nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. The data volume ships empty: no database, space, document or user.

Default user: ubuntu · Architecture: x86_64 (AVX2) · Recommended instance type: m5.large

Prerequisites

  • An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
  • A security group that allows TCP 22 (SSH), TCP 443 (the Vearch API) and TCP 80 (redirects to HTTPS) from your own networks only. Never open 9001, 8817, 8818, 8081 or 2370: they are internal to the instance.

Step 1: Launch the instance

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 Launch through EC2. Choose m5.large or larger (Vearch keeps its vector indexes in memory, so size the instance's memory for your dataset), your key pair and a security group as above. 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.

With the AWS CLI (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}]'

Step 2: Connect to your instance

Version SSH user
Vearch 3.5.9 on Ubuntu 24.04 ubuntu 
ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

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

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

active
active
active
active
FIRSTBOOT_DONE

Vearch's own sockets are those of 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

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

Step 4: Get your URL and password

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

The file is readable by root only:

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 -), so it never appears on a command line or in your shell history.

Step 5: Confirm the API requires the password

Vearch reports a refused request in two ways: the document routes (/document/...) answer HTTP 401, while the cluster routes 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 -k or the instance's certificate, since it is self signed).

Step 6: Create a database and a space, insert vectors and search

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), 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 your own model produces (any dimension) and pick an approximate index such as HNSW or IVFPQ for large collections; the Vearch documentation describes each index type and its parameters. Searches can also filter on scalar fields.

Step 7: Run the built in check

The image ships an end to end check you can run at any time; first boot runs a read only version of it. It reads the credentials file itself and talks to the API over HTTPS through nginx with the instance's certificate pinned: port 80 redirects, an unknown host name is dropped, no password, a wrong password and the upstream default password are refused while the root password works on the same request, and root creates a temporary database whose nearest neighbour search returns the right document, before the database is dropped:

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 cloudimg_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

Step 8: Users and roles

Vearch has role based access control. Create a role with the privileges an application needs and a user bound to it, so 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, 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 not 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. cloudimg'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: the cache routes return stored user records.

Step 9: Security checks

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

How the binaries were built is recorded on the image, 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/cloudimg/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 and 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 internal ports (the master's node registration routes, the metadata store and the monitor's metrics and profiling pages need no password upstream), and the router port only accepts 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 cloudimg_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, never values 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 = cloudimg
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):

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

Step 10: Your own DNS name and certificate, and a new root password

Point a DNS record at the instance, then set the name Vearch is served as. This 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 (if it was ever exposed), run:

sudo vearch-rotate-root-password

It changes the stored root user's password through the API (proving the old one), writes the new sign key to /etc/vearch/config.toml, 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.

Step 11: Outbound connections and S3 backups (off by default)

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, and point backups only at endpoints you trust (ideally an S3 VPC endpoint):

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

Removing it also lets packets from other machines reach Vearch's sockets again; the cloudimg_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 (the other drop-in, 50-cloudimg-imds-deny.conf), so give backups an access key and secret in the request rather than relying on an instance role. To close outbound access again, recreate the file with IPAddressAllow=localhost and IPAddressDeny=any under [Service].

Step 12: Data volume, snapshots and backups

The data directory is its own EBS volume, mounted by filesystem UUID:

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 rather than write 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 it again. The data volume contains the stored user records, so treat its snapshots as secret.

Step 13: Configuration

Settings live in /etc/vearch/config.base.toml (no password in it); /etc/vearch/config.toml is rendered from it 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; it is not set up to join other nodes.

Step 14: Server components

/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/cloudimg/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
Component Version Notes
Vearch 3.5.9 /opt/vearch/bin/vearch, service vearch (master, router and partition server), data /var/lib/vearch (own EBS volume), logs /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; Ubuntu's protobuf, oneTBB and OpenBLAS
nginx 1.24.0 TLS on 443, redirect on 80, site /etc/nginx/sites-available/cloudimg-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.

Troubleshooting

  • curl: (60) SSL certificate problem: the certificate is self signed. Pass --cacert /etc/ssl/vearch/vearch.crt on the instance, -k for a quick test elsewhere, or install your own certificate (Step 10).
  • The connection is closed without a response: the request used a host name the instance does not serve (nginx drops unknown names). Use VEARCH_URL, the instance's IP address, or set your name with vearch-set-hostname.
  • "code":3 with auth header is empty or password is invalid, or HTTP 401: the password is missing or wrong. After vearch-rotate-root-password the root password has changed.
  • Creating a space fails with a replica error: on this single node create spaces with "partition_num":1,"replica_num":1.
  • A backup request fails with a connection error: outbound connections are off by default (Step 11).
  • Vearch does not start after a configuration change: journalctl -u vearch shows the reason; vearch-check-config refuses a missing or default password, authentication turned off, a public master address, profiling ports, cross origin access or a missing data volume. Vearch's own logs are in /var/log/vearch.
  • First boot: journalctl -u vearch-firstboot shows what it did. If it failed, it closed the public listener; fix the cause and run sudo systemctl restart vearch-firstboot.

Security recommendations

  • Restrict the security group to your own networks, and give each application its own user with a narrow role (Step 8) instead of root.
  • Rotate the root password if it was ever exposed.
  • CVE-2026-108746 (Vearch 3.5.2 to 3.5.9, privilege levels of custom roles ignored) has no upstream release yet. This image is Vearch 3.5.9 with cloudimg's backport of the published fix for CVE-2026-108746, not an upstream release; cloudimg modified internal/entity/user.go (diff and notice in /usr/share/doc/cloudimg/vearch/). When Vearch releases a version with the fix, cloudimg publishes a new version built from it and retires this patched build.
  • govulncheck reports five advisories for CubeFS (CVE-2023-46738, CVE-2023-46739, CVE-2023-46740, CVE-2023-46741 and CVE-2023-46742, GO-2024-2430 to GO-2024-2434) because the CubeFS Go module is in the build and the advisories carry no fixed version. They concern CubeFS's object node, master user service, blob store access service and key logging, none of which is in Vearch: Vearch uses only CubeFS's raft library, and the build checks that no other CubeFS package is compiled in. The full report is in /usr/share/doc/cloudimg/vearch/govulncheck-binary.txt.

Support and licensing

cloudimg provides 24/7 technical support by email and live chat: support@cloudimg.co.uk.

Vearch is licensed under the Apache License 2.0 (/usr/share/doc/cloudimg/vearch/LICENSE). This image contains Vearch built from the upstream tag v3.5.9 with the changes listed in /usr/share/doc/cloudimg/vearch/BUILD-PROVENANCE.txt (Go module updates and the CVE-2026-108746 patch, CVE-2026-108746.patch). The engine includes faiss (MIT), RocksDB (Apache 2.0) and CRoaring (Apache 2.0 or MIT); their licences and the third party notices are in the same directory. Vearch is an open source project originally developed at JD.com; cloudimg is not affiliated with or endorsed by JD.com or the Vearch project.