Install and run the Pareo Connector

The Pareo Connector is one container on one virtual machine (VM) in your network. It reads Teamcenter and SAP and sends the result out to Pareo over HTTPS. Pareo never connects into your network (outbound-only). This page tells your IT team and your Pareo admin what to do, in order. Connector security tells your security team what the connector sends and how it proves who it is.

Who does what#

Book one session of about two hours with the Pareo admin and IT together. Finish the checklist below before the session. Most installs stop on a missing permission, not on the install itself.

Before the install: the checklist#

The VM#

The network#

Allow the host names where your firewall can. ingest.pareo.ai resolves to one reserved, static address. If your firewall takes only IP addresses, allow the address that ingest.pareo.ai resolves to. Pareo has no fixed outgoing address: nothing from Pareo calls your network.

• Proxy. The connector supports a proxy with no login or with Basic login. For an NTLM or Kerberos proxy, exempt ingest.pareo.ai from proxy login, or run a local helper such as CNTLM.
• HTTPS inspection. If a firewall or proxy inspects HTTPS, the connector must trust its root certificate. Get the root certificate as a PEM file.
• Internal certificates. Teamcenter and SAP often have certificates from your own certificate authority. The connector must trust that authority too. Put all root certificates into one PEM file, one after the other. The connector reads every certificate in the file.

The Teamcenter technical user#

• A user that logs in with user name and password through the SOA JSON REST interface (/tc/JsonRestServices). The connector cannot log in through single sign-on (SSO) or with a certificate. If your Teamcenter uses SSO for people, ask your Teamcenter admin for a technical user with a direct password login.
• Read access only. No write access.
• Access to one saved query that finds the released materials, and to the revisions it returns. Tell Pareo support the exact name of the saved query.
• The saved query must return fewer than 250,000 objects. If it returns more, make it narrower, for example to one material type or one owning group.
• A password that does not expire during onboarding, or a process to replace it (see Change a password).

The SAP technical user and services#

The connector reads the SAP S/4HANA standard OData APIs. SAP ECC does not have these APIs. If your system is SAP ECC, tell Pareo support before the install.

1. Activate these services in transaction /IWFND/MAINT_SERVICE: API_CLFN_PRODUCT_SRV, API_CLFN_CHARACTERISTIC_SRV, API_BILL_OF_MATERIAL_SRV.

2. Make a technical (system) user with display rights only (authorization activity 03) for these services and their data.

3. Choose the login: Basic (user and password) or OAuth 2.0 client credentials.

4. Test one call from the VM, with the user, before the session. Keep the single quotes: without them the shell deletes $top, and the call reads all bills of materials.

   # Basic
   curl -u <user> 'https://<sap-host>:<port>/sap/opu/odata/sap/API_BILL_OF_MATERIAL_SRV/A_BillOfMaterial?$top=1'
   # OAuth: get a token first, then call with it
   curl -u <client-id> -d grant_type=client_credentials 'https://<sap-host>:<port>/sap/bc/sec/oauth2/token'
   curl -H 'Authorization: Bearer <access_token>' 'https://<sap-host>:<port>/sap/opu/odata/sap/API_BILL_OF_MATERIAL_SRV/A_BillOfMaterial?$top=1'
   

   An answer with data means the service, the user and the network are ready. If SAP uses a certificate of your own certificate authority, add --cacert corp-root.pem. Note the token URL that worked: it goes into sap.token_url.

Connector security lists every entity set the connector reads.

Test systems first#

Start with your test systems. A connector reads test systems or production systems, never both. One organization does not mix the two: Pareo refuses a second connector for the same system in the other environment while the first one is live. To move to production later, see Move from test to production.

Step 1: the Pareo admin creates the connector#

1. In Pareo, open Settings → Connections → Pareo Connector and click Add connector.
2. Enter a Name, for example "Plant A, test systems".
3. Under Source systems are, choose Test systems or Production systems.
4. Under It may send data from, tick the systems this connector reads. Pareo refuses data from any other system, whatever the connector sends.
5. Enter a Plant only if you plan one connector for each plant.
6. Click Save and continue.

7. Click Download install package. Give the file pareo-connector-install.zip to IT through a channel you use for other secrets. It holds the setup key.

The setup key works once and is valid for 30 days. Pareo shows it only in this download. If the file is lost or the 30 days pass, click Issue a new setup key and download. The old key then stops working.

Send to IT by email writes a message in your own mail program with the compose file and the config file. The setup key is never in that message. Give IT the key file separately.

Step 2: IT installs the connector#

Unpack and verify#

1. Unzip the package into one folder on the VM, for example /opt/pareo-connector. It holds compose.yaml, config/connector.yaml, security-sheet.md and secrets/setup.key.

2. Verify the signature and the software bill of materials of the image. Save the public key from Connector security as pareo-connector.pub. Take the image reference from the image: line of compose.yaml:

   cosign verify --key pareo-connector.pub <image>@sha256:<digest>
   cosign verify-attestation --key pareo-connector.pub --type spdxjson <image>@sha256:<digest>
   

   Both commands end with "The signatures were verified against the specified public key".

3. Pull the image and compare its digest with the one you verified:

   docker compose pull
   docker image inspect --format '{{index .RepoDigests 0}}' <image>
   

   The connector also prints a digest on its first log line. That digest is the value of PAREO_IMAGE_DIGEST in compose.yaml. It is not a check of the running image. Use the command above for the check.

Fill in the config file#

Open config/connector.yaml. Change only these lines:

• The times in schedule are UTC if you set no timezone.
• teamcenter.url and sap.url must use https. The connector does not follow redirects.
• The proxy is used only for the calls to Pareo. Calls to Teamcenter and SAP go direct.
• The proxy password is the only secret that is written in config/connector.yaml. Give the file the same file rights as the secret files.

Check the file. The answer names the first error with its line:

docker compose run --rm connector config check

ok   config read, no secrets in it

Put the logins into secret files#

Each login file holds two lines: the user (or OAuth client id) on line 1 and the password (or secret) on line 2. No other text. Write them with a text editor, for example nano secrets/tc_user. A password typed into a shell command stays in the shell history.

TC_TECH_USER
the-password

The container runs as user 65532, not as root. It must be able to read the files. With Docker:

sudo chown -R 65532:65532 secrets
sudo chmod 500 secrets && sudo chmod 400 secrets/*

With rootless Podman, user 65532 in the container is a different user on the VM. Give the files to it with podman unshare:

chmod 500 secrets && chmod 400 secrets/*
podman unshare chown -R 65532:65532 secrets

To change a secret file later, for example a new password or a new setup key, use sudo (Docker) or podman unshare (rootless Podman), for example podman unshare nano secrets/tc_user.

With rootless Podman, also add :Z to each bind mount in compose.yaml on a VM with SELinux, as the comment in the file shows. Never add :Z to the /etc/hostname line: it relabels a system file of the VM.

compose.yaml also mounts the /etc/hostname of the VM, read-only. The connector reports this name to Pareo, and Pareo accepts data only from the approved host name. A new container, for example after an update, keeps the name of the VM, so it stays approved.

Mount the root certificates#

If you set ca_bundle, put the PEM file next to compose.yaml as corp-root.pem. Then remove the # in front of the line ./corp-root.pem:/etc/ssl/corp-root.pem:ro in compose.yaml. The container then sees the file at /etc/ssl/corp-root.pem, the path in ca_bundle. With rootless Podman on a VM with SELinux, add ,Z here too.

Check and start#

1. Run all checks. Nothing is sent.

   docker compose run --rm connector check
   

   ok   trusts the company root certificate from ca_bundle
   ok   reached ingest.pareo.ai through proxy.corp.local
   ..   not joined yet: the source checks run after Pareo approved the connector
   

   The Teamcenter and SAP checks run only after the approval in step 3, because the connector first needs its extraction profile from Pareo. Test the SAP and Teamcenter logins before with your own tools (see the checklist).

2. Start the connector.

   docker compose up -d
   docker compose logs -f connector
   

   With Podman, use podman-compose in place of docker compose.

3. Read the log. Expect these lines:

   ok   connector 1.0.5 (image sha256:a4f9867a4252, as pinned in compose.yaml)
   ok   key pair created on this VM, fingerprint 2CF8 A59B 879F 5EFC D38D F4AD 535B 2651
   ok   setup key accepted
   ..   waiting for approval in Pareo (asks again every minute, no deadline). Compare fingerprint 2CF8 A59B 879F 5EFC D38D F4AD 535B 2651
   

4. Read the fingerprint to the Pareo admin, by phone or in the session. Do not send it through the same channel as the package.

Check your field mapping#

Do this before you approve. The connector reads only the fields of your systems that are mapped to a Pareo field. A field that is not mapped is not read.

1. Open the connector in Pareo and click the tab Field mapping. Each row shows the Pareo field, the name of the field in your system, and the system the connector reads it from.

2. Give the list to the person who approves the data that leaves your network, for example your security team.
3. A row with a warning is not read: two names on one field, a Pareo field that does not exist, or a name the connector cannot read. Click Change on the row and correct the mapping on that page. The tab only shows the mapping. It does not change it.

After the approval, IT can count what the connector would read. Nothing is sent:

docker compose run --rm connector dry-run

ok   teamcenter: 1,812 released materials read from 2,040 revisions in 10 blocks of 200
     field mapping, records with a value:
       "Material code"                1,812 of 1,812
       "REACH status"                 1,640 of 1,812
       "UBA criteria"                     0 of 1,812
     dry run: counted only, nothing was sent.

The dry run prints only names and counts, never a value. A field with 0 records usually has a wrong name in the mapping.

Step 3: the Pareo admin approves#

1. Open the connector in Pareo. The card Waiting for your approval shows the host name, the IP address, the version and the fingerprint.
2. Type the fingerprint that IT reads into Fingerprint IT reads (optional). Pareo compares the two.

3. If the card says Matches the fingerprint Pareo shows, click Approve. If it does not match, do not approve. Click Reject and issue a new setup key.
4. Pareo runs the first checks: the connection to Pareo, the Teamcenter login and saved query, and the SAP login. Nothing is sent during the checks. The result also shows in the connector drawer (see Run it every day). A check that fails names its cause, as in When something goes wrong.

After the approval, the connector fetches its signed extraction profile and starts its first full read at once. It does not wait for the schedule. The log shows:

ok   approved by Pareo, organization <your organization>, may send: teamcenter, sap
ok   extraction profile 0f61bda8b713a564 installed, signature verified
ok   teamcenter login, saved query "<name>": 861 revisions found
ok   sap login, bills of materials readable
     teamcenter run started: full

Check the first sync#

Open Settings → Connections → Pareo Connector → Sync runs. Each run shows its result, the rows it wrote, the rows it withdrew and the batches.

Teamcenter reports more revisions than records. The connector sends one record for each item: the newest released revision. That difference is normal.

A first full read of a large Teamcenter takes time. The connector reads in blocks of 200 records. Each block is one call to Teamcenter.

When a run fails, the log names the cause and the time of the next try, 30 minutes later. Fix the cause. While the first full sync is still missing, docker compose restart connector starts it at once.

What the connector does with incomplete or wrong data#

Your data does not have to be clean. The connector and Pareo check each record alone. A bad record is held back with its reason, and the rest of the run goes in. The run then counts as Partial, and a partial run never withdraws rows.

Records held back show their id and their reason only. Property values never leave the VM in a log.

Run it every day#

• Schedule. By default a delta read runs every day at 02:00 and a full read every Sunday at 03:00 (UTC, unless you set timezone). Only the full read withdraws rows that are gone from the source.
• Status. The connector list shows each connector with its state. OK means it called in during the last minutes and its checks pass.
• Alerts. Pareo tells your Pareo admins through the bell, and Pareo support, when a connector is silent for 2 hours, a run fails or is partial, a run did not reach Pareo's rows, the disk or the spool is full, a check fails, or a new version is available. Each cause is told once.
• Ask the connector. In the connector drawer, the Pareo admin can run the checks, sync named products now, ask for diagnostics, and raise the log level to debug for a short time. A request reaches the connector at its next call, within a minute.

Maintain it#

Change the config file#

Edit config/connector.yaml, then check it:

docker compose run --rm connector config check

The running connector reads the change within a minute. No restart is needed. A config with an error never stops the connector: it keeps the last good config and logs the line of the error.

An older install package mounts ./connector.yaml as a single file. Many editors save a new file in place of the old one, and then the container cannot see the change. With such an install, run docker compose restart connector after each change, or take the volumes lines from a new install package.

Update the connector#

Pareo does not push updates. When a new version is released, the connector page says Version X is available, and the Pareo admins get one notification.

1. Download the install package again in Pareo (no new setup key is needed), or take the new image: line and PAREO_IMAGE_DIGEST from Pareo support.
2. Verify the new image with cosign, as in step 2.
3. Change the image: line and PAREO_IMAGE_DIGEST in compose.yaml. Keep your config folder and your secrets.
4. Run docker compose pull and docker compose up -d.
5. The first log line shows the new version. The connector page shows it within a minute.

To go back, put the old image: line back and run docker compose up -d. The state volume stays.

Pareo has a minimum supported version. Below it, the connector still reports its status, but Pareo takes no data from it, and the page says No longer supported. After the update it syncs again on its own.

Change a password of Teamcenter or SAP#

1. Write the new password into secrets/tc_user or secrets/sap_client, on line 2.
2. Run docker compose run --rm connector check.

No restart is needed. The connector reads the secret files when it uses them.

After a refused login, the connector stops that source so that it does not lock the account. It tries again when the secret file changes, or after connector check. Change the file in Teamcenter or SAP and on the VM at the same time.

Replace the key of the connector#

Do this when the setup key or the VM may be exposed, or when the state volume is lost.

1. The Pareo admin opens the connector and clicks Replace key, then downloads the package with the new setup key. The old key stops working at once.

   

2. IT replaces secrets/setup.key with the new file and restarts the container: docker compose restart connector.

3. The connector sets the old key pair aside, makes a new one and joins again.

4. The Pareo admin compares the new fingerprint and approves again. The synced data stays.

Move the connector to another VM#

1. Stop the old container: docker compose down.
2. The Pareo admin clicks Replace key and downloads the package with the new setup key.
3. IT installs it on the new VM, as in step 2, with the same config folder and secrets.
4. The Pareo admin approves the new host.

Do not copy the state volume to a second VM. Pareo accepts data only from the approved host. A copy shows as Cloned VM and its data is refused.

Back up#

Back up the folder with compose.yaml, config and secrets. The state volume holds the key pair of the connector, its checkpoint and its spool. A backup of the state volume is not needed: if it is lost, replace the key as above, and the next full read reads everything again.

Move from test to production#

1. Revoke the test connector in Pareo.
2. Create a new connector for Production systems, as in step 1.
3. Install it on a VM that reaches the production systems, with production technical users.

The rows from the test connector stay, marked as test data.

A full read is refused#

A full read that returns less than half of what the last full read returned looks like lost access, not like deleted data. Pareo then writes nothing from it, keeps all rows, and tells your Pareo admins: "full read refused, nothing written".

1. Ask IT and the Teamcenter or SAP admin whether the technical user lost rights, or whether the saved query changed. If so, they fix it. The next full read is checked again.
2. If the smaller set is correct, for example after a planned clean-up, the Pareo admin opens the run under Sync runs and clicks Accept this smaller read. Pareo then writes this run and withdraws the rows the source no longer has. Pareo records who accepted it. Later full reads are compared with this run.

Pause, revoke and remove#

• Pause stops all syncs. The connector still calls in. Resume starts them again.
• Revoke stops all data from the connector at once, and it cannot be undone. Synced data stays, with its last sync time.
• To remove the connector from the VM, revoke it first, then run docker compose down -v and delete the folder. -v deletes the state volume with the private key.

When something goes wrong#

Each console line starts with ok, fix or ... A fix line names the cause and the next step. These are the lines you are most likely to see.

What to send Pareo support#

Write to and attach:

1. The output of docker compose run --rm connector check.
2. The last lines of docker compose logs --tail 200 connector.
3. The connector name and the time of the problem.

The log holds record ids, counts and errors, never property values or passwords. Do not send the secrets folder or the setup.key file. Your Pareo admin can also click Send diagnostics: Pareo then gets the settings without secrets, the check results, the last log lines and the run counts.

Who to contact#