KAL
Menu

Menulis Berkas Unit

Mendefinisikan layanan kustom dengan berkas unit systemd.

Daftar isi

Layanan kustom didefinisikan dengan berkas unit systemd, yaitu berkas teks berformat INI yang menjelaskan program apa yang dijalankan dan kapan unit itu diaktifkan. Topik ini membangun satu layanan pengarsip cadangan secara utuh, mulai dari skrip yang dipanggil, anatomi berkas unitnya, sampai pemeriksaan sintaks dengan systemd-analyze sebelum berkas itu dipasang. Skrip dan pemeriksaannya dieksekusi nyata di lingkungan latihan, sedangkan pemasangan akhirnya menuntut systemd yang berjalan.

Skrip yang dijalankan layanan#

Sebelum berkas unit ditulis, program yang akan dijalankan layanan harus sudah benar, karena systemd hanya mengeksekusi perintahnya tanpa memahami isinya. Layanan contoh pada topik ini adalah tugas sekali jalan (oneshot) yang mengarsipkan satu direktori menjadi arsip tar.gz. Direktori contoh yang menjadi sumber arsip disiapkan lebih dahulu:

bash 
# folder kerja dan contoh data yang akan dicadangkan
mkdir -p /tmp/kerja-berkas-unit/dokumen
printf 'catatan rapat mingguan\n' > /tmp/kerja-berkas-unit/dokumen/rapat.txt
printf 'daftar tugas\n' > /tmp/kerja-berkas-unit/dokumen/tugas.txt
printf 'bulan,jumlah\nJanuari,12\n' > /tmp/kerja-berkas-unit/dokumen/rekap.csv
ls -1 /tmp/kerja-berkas-unit/dokumen
text Keluaran 
rapat.txt
rekap.csv
tugas.txt

Skripnya bernama arsip-cadangan.sh dan menerima dua argumen, yaitu direktori sumber dan direktori tujuan. Kedua argumen diberi nilai default agar skrip tetap bisa dicoba tanpa argumen sebagaimana keluaran berikut:

bash arsip-cadangan.sh 
#!/usr/bin/env bash
# arsip-cadangan.sh: membuat arsip cadangan tar.gz dari satu direktori
# Pemakaian: arsip-cadangan.sh [direktori-sumber] [direktori-tujuan]

SUMBER="${1:-/tmp/kerja-berkas-unit/dokumen}"
TUJUAN="${2:-/tmp/kerja-berkas-unit/cadangan}"

if [ ! -d "$SUMBER" ]; then
    echo "Error: direktori sumber $SUMBER tidak ditemukan." >&2
    exit 1
fi

mkdir -p "$TUJUAN"
NAMA="$(basename "$SUMBER")-$(date +%F).tar.gz"
tar -czf "$TUJUAN/$NAMA" -C "$(dirname "$SUMBER")" "$(basename "$SUMBER")"
JUMLAH="$(find "$SUMBER" -type f | wc -l)"
echo "Arsip cadangan selesai: $JUMLAH berkas diarsipkan ke $TUJUAN"
text Keluaran 
Arsip cadangan selesai: 3 berkas diarsipkan ke /tmp/kerja-berkas-unit/cadangan

Setiap barisnya memiliki peran yang jelas:

  • SUMBER dan TUJUAN membaca argumen pertama dan kedua, dengan tanda :- memberikan nilai default untuk percobaan tanpa argumen.
  • Percabangan if menghentikan skrip dengan pesan error dan kode kembali satu apabila direktori sumber tidak ada, sehingga kegagalan tidak merambat ke langkah pengarsipan.
  • mkdir -p menyiapkan direktori tujuan beserta seluruh induknya sekali jalan.
  • NAMA menyusun nama berkas dari nama direktori sumber ditambah tanggal hari ini, sehingga arsip dari hari yang berbeda tidak saling menimpa.
  • tar -czf membuat arsip terkompresi, sedangkan opsi -C mengubah direktori kerja agar isi arsip dimulai dari nama direktorinya, bukan dari jalur penuhnya.
  • JUMLAH menghitung berkas di dalam sumber dengan find dan wc -l, lalu echo melaporkan ringkasannya sebagai bukti kerja.

Menguji skrip sebelum dipasang#

systemd memanggil ExecStart persis seperti pemanggilan program biasa, tanpa shell login dan tanpa terminal, sehingga skrip yang sudah benar di terminal hampir pasti benar pula di bawah layanan. Bukti ujinya sederhana, yaitu skrip disalin ke folder kerja, diberi izin eksekusi, lalu dipanggil dengan dua argumen eksplisit:

bash 
# menyalin skrip ke folder kerja lalu memberi izin eksekusi
cp arsip-cadangan.sh /tmp/kerja-berkas-unit/
chmod +x /tmp/kerja-berkas-unit/arsip-cadangan.sh
# memanggil skrip dengan dua argumen eksplisit
/tmp/kerja-berkas-unit/arsip-cadangan.sh /tmp/kerja-berkas-unit/dokumen /tmp/kerja-berkas-unit/cadangan
text Keluaran 
Arsip cadangan selesai: 3 berkas diarsipkan ke /tmp/kerja-berkas-unit/cadangan

Keluarannya persis sama dengan percobaan tanpa argumen karena kedua argumen eksplisit menunjuk direktori yang sama dengan nilai defaultnya. Pada server sungguhan, skrip dipasang di /usr/local/bin, yaitu direktori untuk program buatan pengelola sistem, lalu diberi izin eksekusi yang sama.

Anatomi berkas unit#

Berkas unit layanan contoh bernama arsip-cadangan.service dan terbagi atas tiga bagian, yaitu [Unit] untuk metadata, [Service] untuk cara eksekusi, dan [Install] untuk aturan enable:

ini arsip-cadangan.service 
[Unit]
Description=Arsip cadangan direktori dokumen

[Service]
Type=oneshot
ExecStart=/usr/local/bin/arsip-cadangan.sh /srv/dokumen /var/backups/arsip

[Install]
WantedBy=multi-user.target
  • Bagian [Unit] menyimpan metadata umum unit. Baris Description= memberi keterangan singkat yang ditampilkan systemctl status dan daftar unit.
  • Baris Type=oneshot menyatakan tugas sekali jalan yang dianggap selesai ketika prosesnya berakhir, berbeda dari layanan yang terus berjalan selama sistem menyala.
  • Baris ExecStart= adalah perintah yang dieksekusi systemd. Jalurnya wajib absolut, dan argumen setelahnya diteruskan kepada program, sehingga baris ini memanggil skrip dengan direktori sumber dan tujuan pada server sungguhan.
  • Bagian [Install] menentukan akibat perintah enable. WantedBy=multi-user.target membuat tautan unit di dalam direktori wants milik target tersebut, yaitu target standar server tanpa antarmuka grafis.

Untuk layanan yang tetap hidup, nilai Type= berubah menjadi simple atau forking sesuai cara program melepaskan dirinya dari pembuatnya, sedangkan bagian lainnya tetap sama. Kesederhanaan oneshot membuatnya cocok sebagai contoh belajar karena seluruh siklus hidupnya selesai dalam satu eksekusi skrip.

Memeriksa berkas unit dengan systemd-analyze#

Kesalahan pada berkas unit baru terasa ketika unit dipasang, kecuali diperiksa lebih dahulu. Perintah systemd-analyze verify membaca berkas unit tanpa menuntut systemd yang berjalan, sehingga pemeriksaan ini bisa dilakukan di mana saja. Berkas unit yang sah menghasilkan keluaran senyap dan kode kembali nol:

bash 
# unit paling sederhana yang sah untuk menguji systemd-analyze
printf '[Unit]\nDescription=Uji unit sah\n\n[Service]\nType=oneshot\nExecStart=/bin/true\n' > /tmp/kerja-berkas-unit/lulus.service
systemd-analyze verify /tmp/kerja-berkas-unit/lulus.service
echo "kode kembali: $?"
text Keluaran 
kode kembali: 0

Berkas unit contoh pada topik ini sengaja menunjuk skrip di /usr/local/bin, dan verify langsung menemukan masalahnya karena berkas itu belum ada di lingkungan latihan:

bash 
# memeriksa berkas unit yang sudah ditulis
cp arsip-cadangan.service /tmp/kerja-berkas-unit/
systemd-analyze verify /tmp/kerja-berkas-unit/arsip-cadangan.service
echo "kode kembali: $?"
text Keluaran 
arsip-cadangan.service: Command /usr/local/bin/arsip-cadangan.sh is not executable: No such file or directory
kode kembali: 1

Pesan Command ... is not executable justru memperlihatkan manfaat verify, yaitu jalur ExecStart diperiksa keberadaannya sebelum unit dipasang. Pada server sungguhan, skrip dipasang lebih dahulu ke lokasi tersebut, sehingga pemeriksaan berakhir senyap. Kesalahan ketik pada nama direktif juga tertangkap, sebagaimana uji berikut pada unit yang kuncinya salah tulis:

bash 
# unit dengan nama kunci yang salah ketik
printf '[Unit]\nDescription=Uji salah ketik\n\n[Service]\nType=oneshot\nExceStart=/bin/true\n' > /tmp/kerja-berkas-unit/salah-ketik.service
systemd-analyze verify /tmp/kerja-berkas-unit/salah-ketik.service
echo "kode kembali: $?"
text Keluaran 
/tmp/kerja-berkas-unit/salah-ketik.service:6: Unknown key 'ExceStart' in section [Service], ignoring.
salah-ketik.service: Service has no ExecStart=, ExecStop=, or SuccessAction=. Refusing.
Unit salah-ketik.service has a bad unit file setting.
kode kembali: 1

Kunci ExceStart tidak dikenal sehingga diabaikan, dan akibatnya unit itu tidak memiliki ExecStart= sama sekali, lalu berkasnya dinilai rusak secara keseluruhan. Ketiga keluaran di atas menunjukkan pola pelaporannya, yaitu nama berkas, nomor baris bila relevan, dan kalimat penyebabnya.

Memasang berkas unit#

Berkas unit buatan pengelola dipasang di /etc/systemd/system, sedangkan /usr/lib/systemd/system adalah wilayah manajer paket yang isinya dapat tertimpa pembaruan. Langkah pemasangannya berurutan, yaitu menyalin skrip dan berkas unit, memuat ulang daftar unit, lalu mengaktifkan layanannya:

bash 
# tidak-dijalankan
# pemasangan menuntut hak root dan systemd yang berjalan, keduanya tidak ada di sandbox
sudo cp arsip-cadangan.sh /usr/local/bin/
sudo cp arsip-cadangan.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now arsip-cadangan.service

daemon-reload wajib karena systemd tidak memantau berkas baru di disk, sedangkan enable --now sekaligus membuat layanan aktif saat boot dan menjalankannya sekarang. Berkas yang sudah terpasang dapat diperiksa dengan systemctl cat arsip-cadangan.service, yang menampilkan isi berkas efektif beserta lokasinya. Apabila layanan perlu diubah, sunting berkasnya di /etc/systemd/system, berikan daemon-reload, lalu jalankan ulang layanannya. Penyuntingan tidak pernah dilakukan pada berkas di /usr/lib/systemd/system. Setelah dipasang, hasil eksekusinya dapat dipantau lewat systemctl status arsip-cadangan.service, dan arsip yang dihasilkannya menumpuk di /var/backups/arsip sesuai argumen pada ExecStart.

Kesalahan umum#

  • Menulis jalur relatif pada ExecStart=. systemd tidak menjalankan shell dan tidak mencari program lewat PATH untuk perintah utamanya, sehingga jalurnya wajib absolut.
  • Melupakan chmod +x pada skrip. verify melaporkan Command ... is not executable, dan layanan yang tetap dipasang berakhir gagal dengan status 203 karena programnya tidak bisa dieksekusi.
  • Menaruh unit buatan sendiri di /usr/lib/systemd/system. Direktori itu milik manajer paket dan isinya dapat tertimpa pembaruan, sedangkan unit kustom ditaruh di /etc/systemd/system.
  • Menyunting berkas unit lalu heran karena tidak berpengaruh. systemd membaca berkas ke memorinya, sehingga daemon-reload wajib diberikan setiap kali berkasnya berubah.

Ringkasan#

  • Layanan sekali jalan didefinisikan oleh tiga bagian berkas unit, yaitu metadata [Unit], cara eksekusi [Service], dan aturan enable [Install].
  • ExecStart wajib berupa jalur absolut ke program yang siap dieksekusi, sehingga skripnya diuji dulu secara manual sebelum dipasang.
  • systemd-analyze verify memeriksa sintaks dan jalur ExecStart tanpa menuntut systemd yang berjalan, dan hasil senyap dengan kode kembali nol berarti sah.
  • Unit kustom dipasang di /etc/systemd/system, diikuti daemon-reload dan enable --now agar aktif sejak boot sekaligus berjalan saat itu juga.

Referensi#