Tools
Tools indeholder scripts primært beregnet til at køre natlige jobs og restore af data efter fejlede jobs.
- job-runner.sh - excutable beregnet til at blive kaldt fra crontab uden parametre
- clear_mox_tables.py - beregnet til at tømme os2mo's tabeller ved nyindlæsning
- cron-restore.sh - beregnet til at restore OS2MO til før den kørsel, som backuppen er taget efter
- moxklas.sh - beregnet til at oprette klasser i LORA - udenom OS2MO ved specialle behov
- prefixed_settings.sh - beregnet til at eksportere settings fra en JSON-fil og ind i current shell environment
- renew-keytab.sh - beregnet til at oprette/genskabe keytabs
- update-dipex.sh - beregnet til at opdatere dette git-repo med ny kode, requirements etc
job-runner.sh#
Important
Det er nødvendigt at ændre gruppeejerskab, så det er alignet med den gruppe, der kører docker, Denne gruppe skal eje både hele os2mo-data-import-and-export og det directory hvor konfigurationsfiler ligger I praksis betyder det for os at vi ændrer ejerskabet på det dertil indrettede CRON-dicrectory i systembrugerens hjemmemappe.
Afvikling af cron-jobs#
Job runner scriptet er ment til at blive kaldt fra crontab på kundens maskiner Dets arbejde er:
- at læse konfigurationen fra settings/settings.json, som er et symbolsk link til settings-filen for systemet.
- at køre de prædefinerede dele af nattens cronjob forudsat at de er slået til i konfigurationen
- at lave en backup af databasen og andre filer, der skal i spil for at få systemet tilbage til en veldefineret tilstand
Læsning af konfiguration#
Konfigurationen kan se således ud:
{
"crontab.SVC_USER": "USER@KOMMUNE.NET",
"crontab.SVC_KEYTAB": "/path/keytab-file",
"crontab.CRON_BACKUP": "/path/backup-dir",
"crontab.CRON_LOG_FILE": "/path/cron-log-file",
"crontab.RUN_MOX_DB_CLEAR": false,
"crontab.RUN_CHECK_AD_CONNECTIVITY": false,
"crontab.RUN_BALLERUP_APOS": false,
"crontab.RUN_BALLERUP_UDVALG": false,
"crontab.RUN_QUERIES_BALLERUP": false,
"crontab.RUN_SD_CHANGED_AT": false,
"crontab.RUN_SD_FIX_DEPARTMENTS": false,
"crontab.RUN_SD_DB_OVERVIEW": false,
"crontab.RUN_AD_SYNC": false,
"crontab.RUN_MOX_STS_ORGSYNC": false,
"crontab.RUN_MOX_ROLLE": false,
"crontab.RUN_CPR_UUID": false,
"crontab.BACKUP_SAVE_DAYS": "60",
"crontab.MOX_ROLLE_COMPOSE_YML":"",
"crontab.SNAPSHOT_LORA":"/path/db-snapshot.sql"
}
En konfiguration som ovenstående kører ingen jobs, laver en backup i
/path/backup-dir
og sletter gamle backupper, når de er mere end 60
dage gamle. Det bruger AD-kontoen USER@KOMMUNE.NET
når den skal
connecte til AD og logger ind med /path/keytab-file
, når det behøves
og logger progress til /path/cron-log-file
.
For at enable importen fra SD sættes crontab.RUN_SD_CHANGED_AT
til
true
.
For at enable exporten til STS Organisation, sættes
crontab.RUN_MOX_STS_ORGSYNC
til true
.
For at enable exporten to Rollekataloget, sættes crontab.RUN_MOX_ROLLE
til true
og crontab.MOX_ROLLE_COMPOSE_YML
udfyldes med stien til den
gældende docker-compose.yml file for Rollekatalogseksporten.
Ideen er at dette script kan kaldes fra cron, finder sin egen
konfiguration, kører programmerne, hvorefter det laver en backup af
/path/db-snapshot.sql
og andre filer, der er nødvendige for at komme
tilbage til en veldefineret tilstand.
Der kan være mere konfiguration nødvendig for de enkelte jobs - se disse for detaljer
Mountpoints#
Tilvejebringelse (og afslutning) af mountpoints styres af et script, cronhook.sh, som kaldes før og efter job-runner.sh. Dette script afvilker scripts i cronhook.pre.d og cronhook.post.d, hvis de er slået til i settings Sripts her afvikles i alfabetisk orden, og de bør hver især brokke sig over de settings de mangler
For at mounte opus-filer ind fra et windows share anvendes følgende settings:
- cronhook.mount_opus_on: true/ false
- cronhook.mount_opus_share - en windows unc-sti
- cronhook.mount_opus_mountpoint - det mounpoint hvor sharet mountet
- cronhook.mount_opus_username - brugernavn til sharet
- cronhook.mount_opus_password - password til sharet
For at unmounte efter kørslen sættes denne setting, men lad være med det. Det besværliggør fejlfinding, hvis ikke der hele tiden er kontakt til filerne
- cronhook.unmount_opus_on: true/false
Husk at mountpoints på windows ofte indeholder $
-tegnet. Et sådan skal
i settings escapes som \$
Kørsel af jobs#
job-runner.sh er ikke et smart program. Det er til gengæld simpelt. Job-afviklingen foregår i 3 afdelinger: imports, exports og reports.
- For alle jobs i imports og exports gælder at et fejlet job stopper afviklingen af de resterende jobs i den pågældfende afdeling
- Hvis imports går galt, afvikles hverken exports eller reports
- Hvis imports går godt forsøges både exports or reports afviklet
I ovenstående konfiguration kan man slå jobs til med alle de
tilgængeglige crontab.RUN_*
, som dækker over:
RUN_MOX_DB_CLEAR
- Tøm OS2mo's databaseRUN_CHECK_AD_CONNECTIVITY
- Check at der er di korrekte rettigheder i ADRUN_SD_FIX_DEPARTMENTS
- Kør SD-fix-departmentsRUN_SD_CHANGED_AT
- Kør SD-changed-at - deltaimport af ændringer fra SDRUN_SD_UPDATE_PRIMARY
- Kør Primærberegning af SD-employeesRUN_BALLERUP_APOS
- Indlæs til OS2MO fra APOS (Ballerups version)RUN_OPUS_DIFF_IMPORT
- Kør Opus diff import - deltaimport af øndringer fra OPUSRUN_AD_SYNC
- Kør en AD-synkroniseringRUN_BALLERUP_APOS
- total-indlæsning af APOS i BallerupRUN_BALLERUP_UDVALG
- udvalgshierarkiet i Ballerups OS2MORUN_MOX_ROLLE
- overførslen til rollekatalogetRUN_MOX_STS_ORGSYNC
- Overførslen til STS OrganisationRUN_QUERIES_BALLERUP
- Ballerups exports / forespørgslerRUN_EXPORT_EMUS
- Kør Eksport til EMUSRUN_CPR_UUID
- Lav en cachefile med CPR/UUID-sammenhænge - gøres typisk før en genindlæsning/restoreRUN_EXPORTS_TEST
- Kør ingenting, men viser at job-runner har været i gangRUN_SD_DB_OVERVIEW
- Kør overbliksrapport over SD-indlæsningens progress (datoer)RUN_OPUS_DB_OVERVIEW
- Kør overbliksrapport over OPUS-indlæsningens progress (datoer)RUN_AD_GROUP_INTO_MO
- Importer en gruppe af eksterne ansatte som ikke findes i lønsystemet
Pakning og lagring af Backup#
Filer til backup er angivet i 3 afdelinger (bash-arrays):
BACK_UP_BEFORE_JOBS
- fil lagres i backup inden kørslen af de enablede jobs afviklesBACK_UP_AFTER_JOBS
- fil lagres i backup efter at kørslen af de enablede jobs er afvikletBACK_UP_AND_TRUNCATE
- fil lagres i backup efter at kørslen af de enablede jobs er afviklet, hvorefter fil trunkeres til størrelse 0. Dette er praktisk til logfiler, som nu pakkes sammen med det datagrundlag, der skal til for at gentage kørslen.
Pakning af backup foregår i to afdelinger:
- pre_backup - her pakkes alle filer i
BACK_UP_BEFORE_JOBS
sammen i en tidsstemplet tarfil - post_backup - her pakkes filerne i
BACK_UP_AFTER_JOBS
ogBACK_UP_AND_TRUNCATE
ned i tarfilen, som gzippes og filerne iBACK_UP_AND_TRUNCATE
trunkeres.
Lagringen af backup foregår i servicebrugerens hjemmedirectory, se
crontab.CRON_BACKUP
i konfigurationseksemplet ovenfor.
Afvikling af et enkelt job udenom cron#
Det kan, for eksempel under udvikling eller test, være nødvendigt at starte et program manuelt. Den mulighed har man også med job-runner scriptet. Man giver simpelhen navnet på den indre funktion med i kaldet.
Herefter læses konfiguration på normal vis, men der tages nu ikke hensyn til om jobbet er slået til i konfigurationen eller ej, det køres
Følgende interne funktioner kan kaldes:
- imports_test_ad_connectivity
- imports_sd_fix_departments
- imports_sd_changed_at
- imports_opus_diff_import
- imports_sd_update_primary
- imports_ad_sync
- imports_ballerup_apos
- imports_ballerup_udvalg
- exports_mox_rollekatalog
- exports_mox_stsorgsync
- exports_os2mo_phonebook
- exports_cpr_uuid
- exports_viborg_emus
- reports_sd_db_overview
- reports_opus_db_overview
- exports_queries_ballerup
- exports_test
- imports
- exports
- reports
Vil man for eksempel afvikle mox_stsorgsync, anvender man kaldet:
tools/jon-runner.sh exports_mox_stsorgsync
dotning / (sourcing) af job-runner.sh#
Man kan source (. tools/job-runner.sh) for at få sat sit environment op. Dermed kan man få adgang til at anvende samme backup/restore funktionalitet, som anvendes af job-runner.sh / cron-restore.sh. Se tools/opus_import_all.sh for hvordan man angiver filer, der skal backes op måske trunkeres efterfølgende. Det er vigtigt at du bruger dit eget suffix - se her også eksemplet i opus_import_all.sh
job-status json-logning#
i settings findes mulighed for at logge til distribueret log. Det er
værdien crontab.CRON_LOG_JSON_SINK
, der bestemmer, hvor loggen
skrives. Hvis den er slået til skrives der jsonlines til denne fil med
status på både de store linier og de enkelte jobs. Hvis den ikke er
slået til, gives der en warning i det almindelige logoutput.
I tillæg til denne fil pakker vi de jsonlinier, der vedrører nærværende
kørsel af job-runner, ned i den backup-fil, som vedrører kørslen. Det
sker ved at vi skriver til filen crontab.CRON_LOG_JSON
, som trunkeres
efter pakning til log og kørsel.
job-status metrikker til prometheus#
Magenta anvender tidsseriedatabasen Prometheus til at opsamle metrikker
på udstrækningen af de jobs, der afvikles af job-runner.
Konfigurationsværdien crontab.CRON_LOG_PROM_API
styrer både hvorvidt
denne funktionalitet er slåt til og hvor man kalder api'et, som typisk
vil være igennem en såkaldt push-gateway på localhost.
clear_mox_tables.py#
Dette anvendes typisk kun af cron-restore
og dér, hvor man hver nat
genindlæser OS2mo fra APOS.
cron-restore.sh#
Tømmer OS2MOS database og indlæser backup i mo og pakker den tilhørende run-db ud. Run-db er den lille sqlite-database, som fortæller SD-changed-at/opus_diff_import hvor langt den er kommet in indlæsningen.
Programmet køres som root på følgende måde:
bash tools/cron-restore.sh backupfil.tar.gz
backupfil.tar.gz
er så en af de daterede filer, der ligger under
sti-til-service-bruger/CRON/backup
Programmet er 17/3 2020 skrevet om til at håndtere os2mo under docker.
moxklas.sh#
Anvendes under implementering til at oprette klasser i Lora. Nogle gange også efterfølgende. Scriptet er simpelt, men ikke så simpelt at kalde:
For at oprette en Email-addresse-klasse med en predefineret uuid under facetten employee_address_type udføres:
uuid=68d3d0ce-9fde-11ea-80b1-63a0ea904cea facet=employee_address_type bvn=test-moxklas titel=test-moxklas scope=EMAIL bash tools/moxklas.sh
Man kan provokere et dry-run ved at sætte en parameter efter hele linien
uuid=68d3d0ce-9fde-11ea-80b1-63a0ea904cea facet=employee_address_type bvn=test-moxklas titel=test-moxklas scope=EMAIL bash tools/moxklas.sh 42
Ovenstående sender et payload til lora, som opretter en klasse som ligner nedenstående
{
"attributter": {
"klasseegenskaber": [
{
"brugervendtnoegle": "test-moxklas",
"titel": "test-moxklas",
"omfang": "EMAIL",
"virkning": {
"from": "1930-01-01 12:02:32",
"to": "infinity"
}
}
]
},
"tilstande": {
"klassepubliceret": [
{
"publiceret": "Publiceret",
"virkning": {
"from": "1930-01-01 12:02:32",
"to": "infinity"
}
}
]
},
"relationer": {
"ansvarlig": [
{
"uuid": "8a2ae31b-422a-4374-b3a8-a2ed4ed23c63",
"virkning": {
"from": "1930-01-01 12:02:32",
"to": "infinity"
},
"objekttype": "organisation"
}
],
"facet": [
{
"uuid": "332e8b38-68c3-4457-a5fb-3332216bb7a6",
"virkning": {
"from": "1930-01-01 12:02:32",
"to": "infinity"
}
}
]
}
}
opus_import_all.sh#
Anvendes under initialindlæsning af opus filer til det mellemliggende trin, der er imellem den første komplette indlæsning og det tidspunkt, hvor man bare indlæser filen fra natten før. Programmet forsøger at indlæse alle opus-filer på en gang, og skulle det fejle markeres programmet efter et ekstra fejlet gennemløb og backup skal derefter indlæses.
Programmet kører som root med:
bash tools/opus_import_all.sh
Opus_import_all.sh
anvender intensivt settings/settings.json. Se under
Opus-indlæsning i dokumentationen for at finde ud af hvilke settings,
der skal være defineret for indlæsning fra Opus.
Programmet slutter af med at fortælle hvilken dato, der tilhører hvilken
logfil, så man kan spole tilbage fra før fejlen opstod. 'At spole
tilbage' gøres så med tools/cron-restore.sh
prefixed_settings.sh#
prefixed_settings sources og anvender to environment-variable, med følgende defaults:
export SETTING_PREFIX=${SETTING_PREFIX:=crontab}
export CUSTOMER_SETTINGS=${CUSTOMER_SETTINGS:=/opt/settings/customer-settings.json}
Det omsætter værdier fra ovenstående konfigurationsfil, fjerner et prefix og eksporterer værdierne
Med øverststående konfigurationsfil ville der efter en sourcing af scriptet eksistere en nøgle SVC_USER i environment med værdien USER@KOMMUNE.NET
renew-keytab.sh#
Dette interaktive program gør det muligt med lidt trial-and-error, når man skal have frembragt en brugbar keytab-fil.
update-dipex.sh#
Dette program anvendes for at opdatere repositoriet og afhængigheder
inspect_config.py#
compare settings file with kommune-anddeby.json
and report what is
missing
job-runner.d#
Job-runner.d er konponenter, der loades af job-runneren Indtil nu loades funktionen, der afvikler jobs herigennem ligesom nyeste tilføjelse: tidsmålinger gør.
terminate_orgfunc.py#
Et tool, som terminerer ALLE brugeres adresser og it-forbindelser. Det er jo ikke særligt smart at køre sådan et, for så skal man oprette dem allesammen igen. Det er imidlertid nødvendigt, hvis man er Viborg og tidligere har brugt Skole-AD eller man ændrer feltmapning